PDP Client APIs


Overview

PDP offers several standard API options for client accounts with certified users. These accounts can purchase a license to utilize the APIs to obtain data to meet their business requirements. Explore how to integrate PDP into internal processes (flowchart).

Licensing of PDP Client APIs includes:

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

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

    Examples of information for each option available are on the following pages.

  3. CSV downloading of API exclusive data is included with regular data from the View All page for options B and C.

PDP-API-diagram-final

Client APIs

Option A: ProScan report

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

proscan-report-personal

 

Personal Reports

  • Personal Dynamics
  • Personal Strengths
  • Data Sheet
  • Intensity Chart
  • Motivators Worksheet

Management Reports

  • Executive Summary
  • Management Guide
  • 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

 

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)

  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 APIs: Describes 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 send payment to PDP Global.

 

Activation of API License

Once the API license has been activated, the Key Contact user will go to their My Information > API Configuration area to insert the webhook URI (provided by client developer) and generate a password (to be provided back to the client developer). If a password is lost or forgotten, a new password can be generatedif this step is taken, 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 Survey Completion Webhook

Upon completion of a survey, whether manually entered, from an invitation or a 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 (i.e. employee id)
    }

    Example payload:

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

PDP Customer APIs

General Notes
 
These APIs may be called by a customer to PDP. They require TLS 1.2. (Older versions like 1.0 and 1.1 are not supported.)
 
Authentication
  • PDP will provide a service username and password for API access
  • Authentication will be using Basic Authentication
  • The header will be in the format: Authentication: Basic {credentials}
  • The credentials are Base64 encoded username and password, separated by a colon (:)
  • The username and password are managed in the My Information by the Key Contact of an Account
  • 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,
    respondentExternalId: String optional,  // passed to PDP via API or survey link, or 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,

    // optional: 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,
    }

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

    // optional: 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,
         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 specific in the Get Survey Results API
    • Response: 
    • mime-type: application/.pdf