Integration Examples

Most Common Steps

The following is a detailed walk-through of the best practices and API methods to be used for an integration in which the behavioral and cognitive assessments are initiated by an external system, usually an Applicant Tracking System (ATS), using an automated email message to candidates and an optional assessment status webhook to signal completion and then transfer results into the ATS. 

API Key Management

The API Key that you generated in the PI Software must be included in the header of each HTTP request and is defined as follows:

Heading

Heading

Heading

api-key

API Key generated using the instructions shown here.

1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6

Retrieve all jobs in software account and store Titles and JobIds

*Note: Leave all parameters blank to retrieve all jobs in the software account or specify them to retrieve specific jobs. Only $skip, $top and $orderby OData options are supported. Ordering by CreatedDate is the default but ordering by Title is also supported.

Request

GET https://integrations.predictiveindex.com/api/v1/jobs/[?JobId][&ExternalJobId][&Title]

Parameters

Name

Required

Type

Description

JobId

false

string

Format - uuid. The Job's unique identifier provided by the PI Software.

ExternalJobId

false

string

The job’s (optional) external identifier

Title

false

string

Job title

Example Request

curl -X GET --header 'Accept: application/json' --header 'api-key: YOUR_APIKEY_GOES_HERE' 'https://integrations.predictiveindex.com/api/v1/jobs/'

Example Response

HTTP/1.1 200 OK

content-type: application/json; charset=utf-8

date: Wed, 26 Jun 2024 12:18:33 GMT

request-context: appId=cid-v1:8e0adc80-aa92-409c-9ab3-75d11a1998c6

transfer-encoding: chunked

vary: Origin

{
    "totalRecords": 4,
    "recordsReturn": 4,
    "records": [{
        "targetFactorRanges": {
            "aSigmaRangeLow": 0.74,
            "aSigmaRangeHigh": 1.74,
            "bSigmaRangeLow": 0.20,
            "bSigmaRangeHigh": 1.20,
            "cSigmaRangeLow": -1.94,
            "cSigmaRangeHigh": -0.94,
            "dSigmaRangeLow": 0.00,
            "dSigmaRangeHigh": 1.00
        },
        "totalCandidates": 0,
        "createdTime": "2024-06-20T14:26:19.1183055",
        "description": null,
        "title": "Tester Testing",
        "externalJobId": null,
        "jobId": "dcbfaea4-3b32-44ee-a51e-ea22e1540665"
    }, {
        "targetFactorRanges": {
            "aSigmaRangeLow": -0.50,
            "aSigmaRangeHigh": 0.50,
            "bSigmaRangeLow": -0.50,
            "bSigmaRangeHigh": 0.50,
            "cSigmaRangeLow": -0.50,
            "cSigmaRangeHigh": 0.50,
            "dSigmaRangeLow": -0.50,
            "dSigmaRangeHigh": 0.50
        },
        "totalCandidates": 1,
        "createdTime": "2024-05-20T15:48:42.3802631",
        "description": null,
        "title": "Power Ranger",
        "externalJobId": null,
        "jobId": "30ffd9f0-65ec-4ffb-8e9d-0434f75686a4"
    }, {
        "targetFactorRanges": {
            "aSigmaRangeLow": -0.12,
            "aSigmaRangeHigh": 0.88,
            "bSigmaRangeLow": 0.61,
            "bSigmaRangeHigh": 1.61,
            "cSigmaRangeLow": -1.55,
            "cSigmaRangeHigh": -0.55,
            "dSigmaRangeLow": -0.94,
            "dSigmaRangeHigh": 0.06
        },
        "totalCandidates": 0,
        "createdTime": "2023-06-29T14:37:23.5151339",
        "description": null,
        "title": "Sales",
        "externalJobId": null,
        "jobId": "1035af5d-e8be-4ae4-8315-215f9dc30a2a"
    }, {
        "targetFactorRanges": {
            "aSigmaRangeLow": -0.11,
            "aSigmaRangeHigh": 0.89,
            "bSigmaRangeLow": -1.44,
            "bSigmaRangeHigh": -0.44,
            "cSigmaRangeLow": -0.49,
            "cSigmaRangeHigh": 0.51,
            "dSigmaRangeLow": 0.05,
            "dSigmaRangeHigh": 1.05
        },
        "totalCandidates": 9,
        "createdTime": "2023-06-29T14:25:34.1801872",
        "description": null,
        "title": "Sales",
        "externalJobId": null,
        "jobId": "2e061395-9c77-4aa0-b044-8350c77db03b"
    }]
}

Search for existing behavioral assessment for a candidate by email address and use results if they exist.

*Note: Only $skip and $top OData options are supported. This request can also be used to retrieve job fit scores once the assessment has been completed.

Request

curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/?PersonId=[PersonId]&Email=[Emai]l&ExternalPersonId=[ExternalPersonId]&JobId=[JobId]&ExternalJobId=[ExternalJobId]" -H "Cache-Control: no-cache" -H "api-key: YOUR_APIKEY_GOES_HERE"

Parameters

Name

Required

Type

Description

PersonId

false

string

Format - uuid. The Person's identifier provided by the PI Software.

Email

false

string

The Person's email

ExternalPersonId

false

string

The Person's (optional) external identifier.

JobId

false

string

Format - uuid. The identifier of the Job associated with the Candidate provided by the PI Software.

ExternalJobId

false

string

The (optional) external identifier of the Job associated with the Candidate

Example Request

curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/?Email=johnsmith@predictiveindex.com" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••"

Example Response

HTTP/1.1 200 OK

content-type: application/json; charset=utf-8

date: Wed, 26 Jun 2024 12:26:48 GMT

request-context: appId=cid-v1:8e0adc80-aa92-409c-9ab3-75d11a1998c6

transfer-encoding: chunked

vary: Origin

{
    "totalRecords": 1,
    "recordsReturn": 1,
    "records": [{
        "person": {
            "personId": "29b1a6f1-6ec7-4aad-9250-bcdf7610f320",
            "isBookmarked": true,
            "genderDescription": "Not Set",
            "email": "faketest@predictiveindex.com",
            "externalPersonId": "Test1",
            "firstName": "Fake",
            "gender": 0,
            "lastName": "Test",
            "middleName": “Integration"
        },
        "job": {
            "description": null,
            "title": "Power Ranger",
            "externalJobId": null,
            "jobId": "30ffd9f0-65ec-4ffb-8e9d-0434f75686a4"
        },
        "behavioralAssessment": {
            "behavioralAssessmentId": "1dc1057b-0dcc-4bd4-93fc-f6e708373df3",
            "behavioralFitRating": 4,
            "referenceProfileName": "Promoter",
            "assessmentState": 40,
            "assessmentStateDescription": "Completed",
            "assessmentUrl": "https://assessment.predictiveindex.com/v1/f9ab968e-5fae-438c-a7d3-d90f9c628707/1dc1057b-0dcc-4bd4-93fc-f6e708373df3?type=emailba"
        },
        "cognitiveAssessment": {
            "cognitiveAssessmentId": "27598451-fbd3-408b-8531-1535369eff30",
            "cognitiveFitDescription": "",
            "cognitiveScore": null,
            "assessmentState": 20,
            "assessmentStateDescription": "AvailableMarked",
            "assessmentUrl": "https://assessment.predictiveindex.com/27598451fbd3408b85311535369eff30?type=cog"
        },
        "candidateUrl": "https://app.predictiveindex.com/pi/hire/jobs/30ffd9f0-65ec-4ffb-8e9d-0434f75686a4/person/29b1a6f1-6ec7-4aad-9250-bcdf7610f320"
    }]
}

Request

curl -v -X PATCH "https://integrations.predictiveindex.com/api/v1/candidates/personId" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "api-key: •••••••••••••••••••••••••••••••••••••••••••••••••••••"

Parameters

Name

Required

Type

Description

personId

true

string

Format - uuid. The Person's unique PI identifier.

Request Body

--data-raw "{

    \"person\": {

    \"email\": \"string\",

    \"externalPersonId\": \"string\",

    \"firstName\": \"string\",

    \"gender\": 0,

    \"lastName\": \"string\",

    \"middleName\": \"string\",

    \"isBookmarked\": true

    },

    \"jobId\": \"string\"

}"

Example Request

curl -v -X PATCH "https://integrations.predictiveindex.com/api/v1/candidates/29b1a6f1-6ec7-4aad-9250-bcdf7610f123" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "api-key: •••••••••••••••••••••••••••••••••••••••••••••••••••••" --data-raw "{ 

\"jobId\": \"3FA85F64-5717-4562-B3FC-2C963F66AA45\"

}"

Example Response

HTTP/1.1 204 No Content

content-length: 0

date: Wed, 26 Jun 2024 12:30:05 GMT

request-context: appId=cid-v1:8e0adc80-aa92-409c-9ab3-75d11a1998c6

vary: Origin

Request

curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/personId/insightspacket" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••"

Parameters

Name

Required

Type

Description

personId

true

string

Format - uuid. The Person's unique PI identifier.

Example Request

curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/29b1a6f1-6ec7-4aad-9250-bcdf7610f123/insightspacket" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••"

Example Response

Note: A byte stream will be returned with the content-type ‘application/pdf’

HTTP/1.1 200 OK

content-disposition: attachment; filename=Test_Fake_Power%2bRanger_CandidateSummary.pdf

content-length: 205036

content-type: application/pdf

date: Wed, 26 Jun 2024 12:05:17 GMT

request-context: appId=cid-v1:8e0adc80-aa92-409c-9ab3-75d11a1998c6

vary: Origin

Request

curl -v -X POST "https://integrations.predictiveindex.com/api/v1/candidates/" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••

Parameters

Name

Required

Type

Description

person

false

See Appendix

The person information

administeredBy

false

See Appendix

The assessment administrator's information. If complete data is not provided, the logged in user's data will be used.

job

false

See Appendix

The Job information. Either a PI Job identifier or an External Job identifier should be provided when creating assessments.

behavioralAssessment

false

See Appendix

The Behavioral Assessment information

cognitiveAssessment

false

See Appendix

The Cognitive Assessment information

sendCognitiveAfterCompletionOfBehavioralAssessment

false

boolean

A flag to indicate that a Cognitive assessment should be sent after the Behavioral assessment has been completed. When this is set to true, Behavioral assessment request configuration will be used to determine the Cognitive assessment to send. Any Cognitive assessment configuration provided with the initial request will be ignored. Set to false if webhook also needs to be called when cognitive assessment is completed or if the cognitive assessment uses a separate webhook.

Example Request

curl -v -X POST "https://integrations.predictiveindex.com/api/v1/candidates/" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••" --data-raw "{

\"person\": {

    \"email\": \"johnsmith@predictiveindex.com\",

    \"firstName\": \"John\",

    \"gender\": 0,

    \"lastName\": \"Smith\",

    \"isBookmarked\": true

    },    

    \"job\": {

    \"jobId\": \"3FA85F64-5717-4562-B3FC-2C963F66A123\"

    },

    \"behavioralAssessment\": {

    \"assessmentStatusWebHookUrl\": \"https://clientwebhookendpoint.clientdomain.com\",

    \"languageLocale\": \"en-US\",

    \"autoSendPIReportToAssessmentTaker\": true,

    \"notifyAssessmentTakerUsingEmail\": true,

    \"sendAdministeredByCompletionEmail\": true

    },

    \"cognitiveAssessment\": {

    \"assessmentStatusWebHookUrl\": \"https://clientwebhookendpoint.clientdomain.com\",

    \"languageLocale\": \"en-US\",

    \"notifyAssessmentTakerUsingEmail\": true

    },

    \"sendCognitiveAfterCompletionOfBehavioralAssessment\": true

}"

Example Response

HTTP/1.1 201 Created

content-type: application/json; charset=utf-8

date: Wed, 26 Jun 2024 12:37:50 GMT

request-context: appId=cid-v1:8e0adc80-aa92-409c-9ab3-75d11a1998c6

transfer-encoding: chunked

vary: Origin

{
    "person": {
        "personId": "5605778f-0012-400b-9aa2-8441ef7d3123",
        "isBookmarked": false,
        "genderDescription": "Unknown",
        "email": "johnsmith@predictiveindex.com",
        "firstName": "John",
        "gender": 0,
        "lastName": "Smith"
    },
    "administeredBy": {
        "email": "janedoe@predictiveindex.com",
        "phone": "5555555555",
        "firstName": "Jane",
        "lastName": "Doe"
    },
    "job": {
        "description": "Sales Manager role",
        "title": "Sales Manager",
        "jobId": "30ffd9f0-65ec-4ffb-8e9d-0434f75686a4"
    },
    "behavioralAssessment": {
        "assessmentId": "03d64bd9-fb9c-4f64-b878-f4eca92a21a2",
        "assessmentUrl": "https://assessment.predictiveindex.com/v1/f9ab968e-5fae-438c-a7d3-d90f9c628707/03d64bd9-fb9c-4f64-b878-f4eca92a21a2?type=emailba",
        "assessmentState": 10,
        "assessmentStateDescription": "Pending",
        "assessmentSentDateTime": "2024-06-26T12:37:48.4398985",
        "autoSendPIReportToAssessmentTaker": true,
        "emailMessage": "Please refer to the instructions below.",
        "emailSubject": "Take the PI Behavioral Assessment",
        "notifyAssessmentTakerUsingEmail": true,
        "sendAdministeredByCompletionEmail": true,
        "assessmentStatusWebHookUrl": "https://clientwebhookendpoint.clientdomain.com",
        "expirationDateTime": "2024-07-07T12:00:00",
        "externalAssessmentId": null,
        "languageLocale": "en-US",
        "redirectURL": null
    },
    "cognitiveAssessment": {
        "assessmentId": "8026ca94-74b6-4ab3-833b-244ce2a6b1aa",
        "assessmentUrl": "https://assessment.predictiveindex.com/8026ca9474b64ab3833b244ce2a6b1aa?type=cog",
        "assessmentState": 10,
        "assessmentStateDescription": "Pending",
        "assessmentSentDateTime": "2024-06-26T12:37:50.1",
        "assessmentStatusWebHookUrl": "https://clientwebhookendpoint.clientdomain.com",
        "externalAssessmentId": null,
        "languageLocale": "en-US",
        "notifyAssessmentTakerUsingEmail": true
    }
}

Example webhook request payload that will be sent to the supplied webhook URL upon assessment completion

{
  "event": {
    "action": "behavioralAssessmentCompleted",
    "id": "5413f3b2-79cf-492e-b858-0b0516f882a4",
    "date": "2024-06-20T15:15:27.0358795"
  },
  "eventDetails": {
    "assessmentId": "03d64bd9-fb9c-4f64-b878-f4eca92a21a2",
    "person": {
      "personId": "5605778f-0012-400b-9aa2-8441ef7d3123",
      "email": "johnsmith@predictiveindex.com",
      "externalPersonId": null,
      "firstName": "John",
      "gender": 0,
      "genderDescription": "Not Set",
      "lastName": "Smith",
      "middleName": null
    },
    "administeredBy": {
      "email": "janedoe@predictiveindex.com",
      "phone": "5555555555",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "job": {
      "title": "Sales Manager",
      "externalJobId": null,
      "jobId": "30ffd9f0-65ec-4ffb-8e9d-0434f75686a4"
    },
    "assessmentSentDateTime": "2024-06-20T15:14:24.3963519",
    "assessmentCompletedDateTime": "2024-06-20T15:15:27.0358795",
    "referenceProfileNumber": 56,
    "referenceProfileName": "Promoter",
    "assessmentState": 40,
    "assessmentStateDescription": "Completed",
    "assessmentUrl": "v1//?type=emailba",
    "assessmentStatusWebHookUrl": "https://webhook.site/5d706869-2ad7-4763-bd57-601276e75918",
    "expirationDateTime": "2024-07-01T12:00:00",
    "externalAssessmentId": null,
    "languageLocale": "en-US",
    "redirectURL": null
  }
}

Appendix

Behavioral Assessments

Field Definitions

  • eventsDetails: Object containing properties specific to the Behavioral Assessment

    • assessmentId : string :  PI generated ID for the individual assessment.

    • externalAssessmentId : string(maxlength: 71) : Client provided ID when creating a new assessment

    • assessmentSentDateTime : DateTime : Date and Time in UTC that assessment was sent to the person.

    • assessmentCompletedDateTime : DateTime : Date and Time in UTC that assessment was completed.

    • referenceProfileName : string : The human readable reference profile value, rendered in English.  

      • Possible values are: Adapter, Venturer, Strategist, Analyzer, Controller, Specialist, Scholar, Individualist, Captain, Maverick, Persuader, Altruist, Collaborator, Promoter, Guardian, Operator, Craftsman

    • referenceProfileNumber : int : The integer reference profile value.  

      • Possible values are: 0 (Adapter), 8 (Venturer), 10 (Strategist), 12 (Analyzer), 14 (Controller), 20 (Specialist), 22 (Scholar), 24 (Individualist), 26 (Captain), 30 (Maverick), 36 (Persuader), 46 (Altruist), 54 (Collaborator), 56 (Promoter), 60 (Guardian),64 (Operator), 70 (Craftsman)

    • languageLocale : string : The language that the assessment was sent in.  The list of possible values can be fetched from here

    • redirectURL : string(maxlength: 500) : The URL that the assessment taker was redirected to upon completion of the assessment.

    • assessmentState : int : An integer representing the current state of the assessment.

      • Possible values are: 10 (Pending), 30 (Started), 40 (Completed), 50 (Expired), 60 (Failed), 65 (Aborted)

    • assessmentStateDescription : string : The human readable assessment state.

      • Possible values are:Pending, Started, Completed, Expired, Failed, Aborted

Cognitive Assessments

Field Definitions

  • eventDetails: Object containing properties specific to the Cognitive Assessment

    • assessmentId : string :  PI generated ID for the individual assessment.

    • externalAssessmentId : string(maxlength: 71) : Client provided ID when creating a new assessment

    • assessmentSentDateTime : DateTime : Date and Time in UTC that assessment was sent to the person.

    • assessmentCompletedDateTime : DateTime : Date and Time in UTC that assessment was completed.

    • languageLocale : string : The language that the assessment was sent in.  The list of possible values can be fetched from here

    • cognitiveFitDescription : string : General fit description based on the score vs the Job’s Cognitive Target. 

      • Possible Values: Moderate fit, Strong Fit, Cautionary fit

    • cognitiveFitRating : int : Cognitive Score on a scale of 100-450.

    • assessmentState : int : An integer representing the current state of the assessment.

      • Possible values are: 10 (Pending), 30 (Started), 40 (Completed), 50 (Expired), 60 (Failed), 65 (Aborted)

    • assessmentStateDescription : string : The human readable assessment state.

      • Possible values are:Pending, Started, Completed, Expired, Failed, Aborted

Summary of major changes for clients that had Legacy integrations

Note: This information is only applicable for legacy clients.

  1. There are four resources around which the APIs are modeled

    1. Jobs

    2. Candidates (replaces Persons from 1.0)

    3. Behavioralassessments

    4. Congnitiveassessments

  2. Where applicable, properties have been grouped/nested by relevance into Person, AdministeredBy, Job objects

    1. AssessmentUser has been renamed to Person

    2. assessmentUserId has been replaced by PersonId

  3. Folders are no longer exposed through API's since they are set during Job creation and candidates inherit their folder assignment from the Job they’re attached to. We would like to learn more about how you and your clients are using Folders if you are using them in your current implementation.

  4. Cognitive Report and Person Snapshot Report are no longer supported