☰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.
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:
api-key
API Key generated using the instructions shown here.
1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6
*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.
GET https://integrations.predictiveindex.com/api/v1/jobs/[?JobId][&ExternalJobId][&Title]
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
curl -X GET --header 'Accept: application/json' --header 'api-key: YOUR_APIKEY_GOES_HERE' 'https://integrations.predictiveindex.com/api/v1/jobs/'
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" }]}*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.
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"
PersonId
false
string
Format - uuid. The Person's identifier provided by the PI Software.
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
curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/?Email=johnsmith@predictiveindex.com" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••"
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" }]}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: •••••••••••••••••••••••••••••••••••••••••••••••••••••"
personId
true
string
Format - uuid. The Person's unique PI identifier.
--data-raw "{ \"person\": {
\"email\": \"string\",
\"externalPersonId\": \"string\",
\"firstName\": \"string\",
\"gender\": 0,
\"lastName\": \"string\",
\"middleName\": \"string\",
\"isBookmarked\": true
},
\"jobId\": \"string\"
}"
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\"
}"
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
curl -v -X GET "https://integrations.predictiveindex.com/api/v1/candidates/personId/insightspacket" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••"
personId
true
string
Format - uuid. The Person's unique PI identifier.
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: ••••••••••••••••••••••••••••••••••••"
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
curl -v -X POST "https://integrations.predictiveindex.com/api/v1/candidates/" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "api-key: ••••••••••••••••••••••••••••••••••••
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
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
}"
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 }}{ "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 }}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
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
Note: This information is only applicable for legacy clients.
There are four resources around which the APIs are modeled
Jobs
Candidates (replaces Persons from 1.0)
Behavioralassessments
Congnitiveassessments
Where applicable, properties have been grouped/nested by relevance into Person, AdministeredBy, Job objects
AssessmentUser has been renamed to Person
assessmentUserId has been replaced by PersonId
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.
Cognitive Report and Person Snapshot Report are no longer supported