PDP Client APIs


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).

Licensing of PDP Client APIs includes:

  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— 

    Option A: ProScan report (.pdf)
    Option B: Basic traits (includes option A)
    Option C: Basic and Priority values (includes options A and B)
    Option D: JobScan applicant match score and reports

    Examples of information returned for each option are below.

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

API Graphic 3

 

Client APIs

 

ProScan Invitations

Included with every option (see options A–D below) is the ProScan Invitation API. This provides an external  programmatic method to create ProScan survey email invitations that will generate client selected ProScan personal and management reports when the respondent submits the survey. Available only for Platinum and Enterprise Solution plans. Excludes Applicant Match survey invitations and reports, Side-by-Side reports, and Job Dynamics Analysis survey invitations.

 

Option A: ProScan report

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

proscan-report-personal

 

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-traitsExample

  • 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 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: Download CSV 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: Download CSV sample

 

 

Licensing PDP Client APIs

Preparation Checklist

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

 

  1. Identify which API option best fits the organization's need:

    Options
    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
  1. Share the Developer Documentation with client programmers to confirm APIs are understood and can be implemented successfully.

    PDP Survey Completed Webhook—Describes the process of how PDPworks’ server notifies client’s server when a survey is completed.

    PDP Client APIsDescribes authentication when client’s server requests from PDPworks’ server:

    • Survey results API (GET)
    • Basic traits API (GET)
    • Basic and Priority values API
    • ProScan report API (GET)

    Sign the API Terms of Service and check which option is to be licensed.

  2. Submit signed document and remit payment.
  3. 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 generatedif this step is taken, the existing webhook will no longer work and client developer will need to update code with the newly generated password for webhook to work again.

 

 

 

Developer Documentation

 

PDP ProScan Invitation API

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

  • URL: https://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,
}
}
}

 

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
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.

  • 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'
externalRespondentId: '34598437',

 

PDP Customer APIs

General Notes

These APIs may be called to PDP by a customer. Calls require TLS 1.2. (TLS 1.0 and 1.1 are not supported.)
 
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—Authentication: Basic {credentials}
  • The credentials are Base64 encoded username and password, separated by a colon (:)
  • More information: https://en.wikipedia.org/wiki/Basic_access_authentication
Get Survey Results API
  • Method: GET
  • Header: Authentication: 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
    basic Traits: {
       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,
    },


    // Option C—available for additional cost
    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: Authentication: Basic {credentials}
    • Method: GET
    • URI: as specified  in the Get Survey Results API
    • Response: 
    • mime-type: application/.pdf