Request a Demo
Menu
Login
Request A Demo

PDP Client APIs

Integration

Overview

PDP offers several standard API options for client accounts with certified users. Client accounts can purchase a license to utilize the APIs to obtain data to meet their business requirements (see options A–D). Contact your Licensed PDP Representative for pricing for each option. Explore how to integrate PDP into internal processes (flowchart).

Licensed PDP Client APIs include:

  1. ProScan Invitation API—(Method: POST) to create ProScan survey invitation email.
  2. PDP Survey Completion Webhook—(Method: POST) informs the client’s server when a survey is completed and passes the following survey identifier information: first name, last name, email, external ID (e.g., employee #). The survey completion webhook triggers for any one of the following type of surveys: ProScan survey invitation completed by a respondent, ProScan Survey Link completed by a respondent, or ProScan manual entry.
  3. Survey Results API—(Method: GET) to retrieve licensed API data.

    API options include
    1. ProScan report (.pdf)
    2. Basic traits (includes option A)
    3. Basic and Priority values (includes options A and B)
    4. JobScan applicant match score and reports
    5. Create Side-by-Side reports

  4. Downloading (.csv) of API exclusive data is included in addition to the standard data from the View All page.

API Graphic v3

 

Client APIs

ProScan Invitations

Included with every option (see option detail below) is the ProScan Invitation API. This provides an external programmatic method to create ProScan or ProScan Applicant Match survey email invitations that will generate client selected ProScan personal, management, and Applicant Match reports when the respondent submits the survey.

Available only for Platinum and Enterprise Solution plans. Excludes  Job Dynamics Analysis survey invitations.

Option A: ProScan report

proscan-report-personal

Any ProScan report selected for a survey can be retrieved as a single report PDF, including:

Personal Reports

  • Personal Dynamics
  • Connect with Me
  • Personal Performance Actions
  • Personal QuickView
  • Personal Strengths
  • Data Sheet
  • Intensity Chart
  • Motivators Worksheet

Management Reports

  • Executive Summary
  • Management Guide
  • Manager QuickView

Option B: Basic traits

Basic/Natural Self trait information. Includes ProScan Report(s) from Option A.

example-basic-traits

Example

  • Profile Structure: P/C/N/E/D (Pace over Conformity over mid-line (N) over Extroversion over Dominance)
  • Highest Trait: Pace
  • Lowest Trait: Dominance
  • Logic: Feeling
  • Primary Energy Style: Allegiance
  • Kinetic Energy: 6

Option B: JSON sample

Option B: CSV download sample

Option C: Basic and Priority values

Basic/Natural Self rounded trait values and Priority Environment trait stress length values for quantitative (vs. categorical) predictive analytics research. Includes ProScan Report(s) from Option A and Basic trait information from Option B.

example-basic-valuesExample of Basic values

  • Dominance: 3
  • Extroversion: 3
  • Pace: 6
  • Conformity: 6

Example of Priority values

  • Dominance Stress: 87
  • Extroversion Stress: 182
  • Pace Stress: -88
  • Conformity Stress: -123
  • Logic Stress: 28
  • Satisfaction: High
  • Energy Drain: -172

Option C: JSON sample

Option C: CSV download sample

Option D: JobScan applicant match score and reports

Any JobScan applicant report selected can be retrieved as a single report PDF response along with applicant match scores, including:Applicant reports

Applicant Reports

  • Applicant Match
  • Candidate Interview
  • Career Path

Example of applicant match score values

  • Job Model Name:  Sales Executive Model
  • Version #:  ver. 3
  • Match score:  73%

Option D: JSON sample

Option D: CSV download sample

Licensing PDP Client APIs

Preparation Checklist

Complete the following steps and ensure that the appropriate PDP Client API option is selected:

  1. Identify which API option best fits the organization's need:
    A. ProScan report
    B. Basic traits (includes ProScan report)
    C. Basic and Priority values (includes ProScan report and Basic traits)
    D. JobScan applicant match score and reports
    E. Create Side-by-Side reports
  2. Share the Developer Documentation with client programmers to confirm APIs are understood and can be implemented successfully.
  3. Sign the contractual  API Terms of Service and check which option is to be licensed.
  4. Submit signed document and remit payment.
  5. Activate API license. See below.

Activation of API License

Once the API license has been activated, the Key Contact user will login at my.PDPworks.com and navigate to their [username] > My Information > API Configuration area to insert the webhook URI (provided by client's developer) and generate a password (to be provided back to the client's developer). If a password is lost or forgotten, a new password can be generated. If this step is taken, the existing webhook will no longer work and the client developer will need to update code with the newly generated password for the webhook to work again.

Developer Documentation

PDP ProScan Invitation API

Programmatically create ProScan or ProScan Applicant survey invitations (excludes  JDA surveys). Available with options A–D.

  • URL: https://www.my.pdpworks.com/external-api/surveyInvitations
  • Method: POST
  • Payload:

{ sender: {
name: String required maxsize 64,
emailAddress: Email required maxsize 256,
organizationName: String required maxsize 128,
languageCode: String optional default 'en' // see Sender and Report language list below for all valid values
},
reportTypeIds: Array of integers optional default 27, 28 minimum 1 report if provided, // see list of valid values below
reportNotificationLevelId: Integer required // see below for valid values,
thirdPartyNotificationEmailAddresses: Array of email (valid format) addresses String maxsize 256,
invitee: {
firstName: String required maxsize 64,
lastName: String required maxsize 64,
emailAddress: Email required maxsize 256,
languageCode: String optional default 'en', // see ProScan survey language list below for all valid values
externalId: String optional maxsize 100,
}
}
}

 

GET JobScan Models API

Request array of all active JobScan Models in the account at the moment of the request. Use the jobModelId: integer with PDP ProScan Invitation API for Applicant Match Invitations. Available with option D.

  • URL: https://www.my.pdpworks.com/external-api/jobModels
  • Header: Authentication: Basic {credentials}
  • Method: GET
  • Payload:

[
     {
           jobModelId: integer,
          jobModelName: string
     }
]

Example payload:

[
    {
        "jobModelId"20283,
        "jobModelName""JobScan Model 1"
    },
    {
        "jobModelId"20282,
        "jobModelName""JobScan Model 2"
    },
    {
        "jobModelId"17013,
        "jobModelName""JobScan Model 3"
    }
]
 

Sender and Report language list

Your account may only have a sub-set of this list available. Ask your account's Key Contact to provide the list of languages activated for the account.

English name
Native name
Code
English English 'en'
Bahasa Indonesia Indonesian 'id'
Español Spanish 'es'
Svenska Swedish 'sv'
日本の Japanese 'ja'
简体中文 Simplified Chinese 'zh-Hans'
繁體中文 Traditional Chinese 'zh-Hant'

 

Invitee/ProScan survey language list

Every account has all of these languages available for displaying an Invitee's survey form. Note that the invitee can select any language before submitting their responses.

English name
Native name
Code
Deutsch German 'de'
English English 'en'
Español Spanish 'es'
Français French 'fr'
Bahasa Indonesia Indonesian 'id'
Italiano Italian 'it'
日本の Japanese 'ja'
한국어 Korean 'ko'
Nederlands Dutch 'nl'
Norsk Norwegian 'no'
Português Portuguese 'pt'
Pусский Russian 'ru'
Slovenščina Slovene 'sl'
Svenska Swedish 'sv'
Kiswahili Swahili 'sw'
Tagalog Tagalog 'tl'
Türkçe Turkish 'tr'
Tiếng Việt Vietnamese 'vi'
简体中文-職務 Simplified Chinese-Job 'zh-Hans-CN'
简体中文-西方 Simplified Chinese-Western 'zh-Hans-TW'
繁體中文-職務 Traditional Chinese-Job 'zh-Hant-CN'
繁體中文-西方 Traditional Chinese-Western 'zh-Hant-TW'

 

Report list

Your account may only have a sub-set of this list available.

Report name
id
Personal Reports
Personal Dynamics 1
Connect with Me 27
Personal Performance Actions 7
Personal QuickView 28
Personal Strengths 3
Data Sheet 4
Intensity Chart 5
Motivators Worksheet 6
Side-by-Side—Natural Self 8
Side-by-Side—Pressures 36
Management Reports
Executive Summary 9
Management Guide 10
Manager QuickView 11

Report notification level IDs

Only to me (sender) 1
Only to third-party(s) 2
Invitee and myself (sender) 3
Third-party(s) and myself (sender) 4
Invitee, third-party(s), and myself (sender) 5
Do not email 6

 

Example Payload

This sends an email with the selected report(s) attached to only the sender of the invitation.

{
"sender": {
"name": "Manager Name",
"emailAddress": "sender@pdpglobal.com",
"organizationName": "Org Name",
"languageCode": "en"
},
"reportTypeIds": [28,27],
"reportNotificationLevelId": 1,
"invitee": {
"firstName": "todd",
"lastName": "test",
"emailAddress": "recipient@pgpglobal.com",
"languageCode": "en",
"externalId": "emp123"
}
}

Example Payload

This sends an email, with the selected report(s) attached, to the sender of the invitation and to one or more third-parties.

{
"sender": {
"name": "Manager Name",
"emailAddress": "sender@domian.com",
"organizationName": "Org Name",
"languageCode": "en"
},
"reportTypeIds": [28,27],
"reportNotificationLevelId": 4,
"thirdPartyNotificationEmailAddresses": [
"thirdparty1@domian.com",
"thirdparty2@domain.com"
],
"invitee": {
"firstName": "todd",
"lastName": "test",
"emailAddress": "recipient@domain.com",
"languageCode": "en",
"externalId": "emp123"
}
}

PDP Survey Completion Webhook

Upon completion of a survey, whether manually entered, from an invitation (created via UI or API) or survey link, the following call will be made from PDP to the customer webhook URI configured in account settings. Upgrading a survey to add one or more additional reports will also trigger the webhook.

  • Method: POST
  • Payload:
event: String required,  //  'survey-completed'<
uri: String required,  //  uri of the survey results
surveyKey: string required,
respondentExternalId: String optional,  //  passed to PDP via API or survey link (e.g., employee id)

Example payload:

{
event: 'survey-completed',
uri: `https://www.my.pdpworks.com/external-api/surveys/AB32DS83`,
surveyKey: 'AB32DS83',
respondentExternalId: '34598437'
}

 

PDP Customer APIs

General Notes

  1. These APIs may be called to PDP by a customer.
  2. Calls require TLS 1.2+. (TLS 1.0 and 1.1 are not supported.)
  3. The customer’s endpoint API must respond with any HTTPS success code (2xx) within 5000ms, otherwise, PDP will retry the call multiple times until successful or the maximum retries is reached.

Tips

  • Keep your code as simple as possible.
  • Log the data sent from PDP and immediately return an HTTPS success status code (2xx).
  • Perform post-processing of the data received from PDP after sending the success status code (2xx) to avoid timeouts and unnecessary retries.

Authentication

  • PDP will provide the service username.
  • The password is managed by the customer's Key Contact in the API Configuration area of the [user] > My Information page in the my.PDPworks.com account.
  • Authentication uses Basic Authentication
  • The header will be in the format—Authorization: Basic {credentials}
  • The credentials are Base64 encoded username and password, separated by a colon (:)
  • More information

Get Survey Results API

  • Method: GET
  • Header: Authorization: Basic {credentials}
  • URI: as specified in the Survey Completion Webhook
{uri: String required, // uri of the survey results
surveyKey: String required,
respondent ExtId: String optional,  // passed to PDP via API or survey link, or manually entered
surveyTakenDateTime: Date required,
surveyTakenUtcDateTime: Date required,
firstName: String optional, lastName: String optional, emailAddress: String (email) optional, organizationName: String optional, phoneNumber: String optional, phoneExtension: String optional, faxNumber: String optional, address1: String optional, address2: String optional, city: String optional, state: String optional, zipCode: String optional, country: String optional, jobTitle: String optional, }

// Option B—available for additional cost
basicTraits: {
   structure: String required,
   highestTrait: String required,  //  may include two traits, comma separated
   lowestTrait: String required,
   logic: String required,
   primaryEnergyStyle: String required,
   kineticEnergy: Number required,
}

// Option C—available for additional cost
basicValues: {
   dominance: Number required
   extroversion: Number required,
   pace: Number required,
   conformity: Number required,
},

priorityValues: {
   dominanceLength: Number required
   extroversionLength: Number required,
   paceLength: Number required,
   conformityLength: Number required,
   logicLength: Number required,
   satisfaction: Number required,
   energyDrain: Number required,
},

// Array of report metadata
reports: [
  {
   uri: String required,
     reportKey: String required,
     reportType: String required,


// Option D—available for additional cost
    applicantMatches: [{
         jobModelName: String required,
       jobModelVersion: Number required, // 1 through 7
      matchScore: Number required, // 0 to 100
}] optional,
createdAt: Date required,   // date report created
  }
]

Get Report API

  • Retrieves a single report as a PDF response
  • Header: Authorization: Basic {credentials}
  • Method: GET
  • URI: as specified in the Get Survey Results API
  • Response: 
  • mime-type: application/.pdf