Integration Best Practices

The following is a detailed walk-through of the best practices and API methods to be used for an integration in which a Predictive Index (PI) assessment is initiated by an external system, usually an Applicant Tracking System (ATS), using an email message to invite candidates and an optional assessment status webhook to signal completion and then transfer results into the ATS. Along the way, various optional considerations are explained.

The following two sections and sequence diagrams represent the most common implementation of an API integration. Other implementations are of course possible, but it is the intent of this article to address the most commonly used strategies.

Part A - Triggered Email Invite, Assessment Completion Calls Webhook

Diagram A:

api administer assessment email image

1. Candidate Selected for Assessment 

A candidate typically is selected to take an assessment in an ATS when one of these occur:

  • Candidate submits a completed online application for a job marked as requiring an assessment 
  • Recruiter manually performs an action within the ATS software to assign an assessment to a candidate

Upon selecting a candidate to take one or more PI assessments, the change in ATS data is used by the integration process to perform the following:

1a. Search for Existing Assessment Taker and Any Assessments

  • Use the candidate's details to determine whether the candidate already has completed the required assessment(s) 
    • Existing ATS data referring to a previously completed assessment
    • Existing assessment data in the PI system obtained through an API call using unique candidate data such as email address or candidate ID from the ATS system stored in the externalPersonId field. See GET peopleandjobs
GET /api/v2/peopleandjobs?$search=somename%40mymail.com
or 
GET /api/v2/peopleandjobs?
     $filter=peopleAndJobsSearchResult%2FassessmentUser%2FexternalPersonId%20eq%20'a75be8a5e5a5'
The response object returned by peopleandjobs includes an assessmentInformation object that includes both behavioral and cognitive assessment details. Based on these details, for example an assessmentState = 40 means "complete", your logic can determine whether assessment results are available or not.

1b. Use Any Completed Assessment Results

If the candidate has already taken all required assessments, no new order should be required. Instead, the existing assessment data should be retrieved and stored according to the current integration design. The assessmentId values returned from the peopleandjobs call above can be used in any API menthods relating to the assessment, and the assessmentUserId can be used in any API methods relating to the person.

If the candidate has an existing complete assessment but you will be using the Job Fit / Match Scoring features of PI, it may be necessary to update the existing person data with a current PI Job name so that the existing behavioral and cognitive assessment results will be compared with the correct PI Job rather than whatever PI Job may have been assigned previously. The API method to use for this PATCH v1\persons\{id}

Example using CURL (line breaks added):

curl -X PATCH --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ \ "associatedJobTitle": "Programmer" \ }' 'https://pi.predictiveindex.com/api/v1/persons/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

1c. Resend Expired or Aborted Assessment Invitation

If the candidate has been assigned an assessment but did not complete it, possibly leaving it in an "expired" state (assessmentState = 50), or if they closed their browser window during a Cognitive assessment (assessmentState=65), it is possible to update the behavioral assessment record with a new expiration date or order a new cognitive assessment and at the same time trigger the PI system to send a notification email to the assessment taker with explanatory text.

When using either method below to overcome expired or aborted assessments by sending new email invitations, it is often desirable to send an explanatory message to the email recipient explaining what is happening. To do this, define values for the following two properties in the JSON being passed:

  • subject- The email subject line to be used in the new email invitation.
  • message- The email body to be used in the new email invitation.

PATCH behavioralassessments/{id} - To update an existing Behavioral assessment, the PATCH verb is used instead of the POST verb, the assessmentId must be passed as a part of the request URL and the body of the request must contain JSON with any properties to be updated. See PATCH behavioralassessment/{id}.

  • resendAssessment - To resend the assessment invitation email, pass the parameter resendAssessment with a value of 1. 
  • expirationDateTime - Available only in the PATCH behavioralassessment method, use this to set a new expiration date (e.g. "2019-02-24")
curl -X PATCH --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ "resendAssessment": true, "expirationDateTime":"2019-02-24", \ "subject":"The Predictive Index Behavioral Assessment - Extended", \ "message":"You have been given extra time to complete the Behavioral Assessment." \ }' 'https://pi.predictiveindex.com/api/v1/behavioralassessments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
POST cognitiveassessments- To send a new Cognitive Assessment after the existing one has expired (assessmentState=50) or had its browser closed prematurely (assessmentState=65), it is best to use a POST cognitiveassessments with the assessmentUserGuid value because when POST is used, the limit of a maximum of 3 cognitive assessments is enforced. 
curl -X POST --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ "assessmentUserGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ "subject":"The Predictive Index Behavioral Assessment - Extended", \ "message":"You have been given extra time to complete the Behavioral Assessment." \}' 'https://pi.predictiveindex.com/api/v2/cognitiveassessments'

1d. Update Existing Person with New Details

Although you may have found an existing person with a completed or expired behavioral assessment which you intend to utilize according to the methods above, it may be necessary to change some details about that person before you proceed.

Changing Job Assignment
For example, if you wish to change the assigned Job because the existing Job data doesn't match the actual Job the person is currently applying for or should be assigned to, you can use one of the following methods to alter the job assigned to the person in question:

Changing Job using Job Title (uses api/v1)

Maybe you have obtained a list of possible jobs from the /api/v3/jobs API method and stored them in a drop-down list in the UI and your UI doesn't support list values that are different from their display values, and now you wish to use the name property from that drop-down to assign the job to the current person.

curl -X PATCH --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ \ "associatedPositionTitle": "Quality Assurance Engineer" \ }' 'https://pi.predictiveindex.com/api/v1/persons/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Changing Job using Job ID (uses api/v3)

Maybe you have obtained the list of possible jobs from the /api/v3/jobs API method and stored them in a drop-down list in the UI, and now you wish to use the jobId property from that drop-down to assign that jobId to the candidate in question.

curl -X PATCH --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ \ "associatedJobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
}' 'https://pi.predictiveindex.com/api/v3/persons/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Changing externalPersonId (uses api/v3)

Maybe you need to update the external person ID because the existing data was created before you integrated with the current external system and need to assign an external person ID for the first time, or PI was integrated with a different external system previously so the new external person ID must be stored.

curl -X PATCH --header 'Content-Type: application/json'
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
-d '{ \ "externalPersonId": "SOMEnewEXTID1234" \ }' 'https://pi.predictiveindex.com/api/v3/persons/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

2. ATS Integration Orders PI Assessment (POST)

When ordering an assessment via the PI API, you must first determine which API method to use based on which type of assessment you are ordering:

You must pass as the POST data a JSON object containing parameters that express several facts and decisions:

  • Identify the Assessment Taker - there are two ways you can specify which person is supposed to take the assessment:
    • Create a new PI person by providing new information about the person, causing a new PI Person object to be created along with the assessment. You cannot specify assessmentUserGuid if providing name and email data.
      • firstNamemiddleName(optional), lastName
      • email
      • externalPersonId(optional) - this is usually a unique identifier from the ATS system up to 71 characters in length. If you pass this value, an action that attempts to create a new PI Person, and that value already exists for another PI Person, you will receive an error and the POST will fail. This is why it is wise to check for an existing person in step 1 above before reaching this step.
      • associatedPositionTitle(optional) - this field must match a Job Target name from the PI software. If this is defined as a parameter and the Job in PI software has a target defined for behavioral pattern and/or cognitive score, then the results of the assessment will include Job Match scores, a very powerful piece of data to use for identifying strong match candidates, even by people who do not yet fully understand the PI behavioral pattern graphs. To obtain a list of all current Job Target names, you can call the API method GET jobs and use from the results the selected name property to assign to associatedPositionTitle.
      • gender(optional) - Male or Female - controls the pronouns used in report language. If no gender is specified for a person, gender must be specified at the time reports are generated (NOTE: the product roadmap includes a move toward gender-neutral reports which will remove the need to specify gender)
      • personType (optional) - Candidate or Employee or Other. The PI software system includes an ability to manage persons and their assessment data according to the type of person they are to the organization. Setting the personType to Candidate for job applicants is wise so that all such people can be managed as a group. However, once a person has been hired, it is also wise to change their personType to Employee so they will no longer be managed like a Candidate.
    • Refer to an existing PI person by providing the assessmentUserGuid of an existing PI Person to which the assessment should be linked. If you provide this parameter value, you cannot also provide values for the parameters used to define a new PI person as described above. Note: The value given to input parameter assessmentUserGuid should be the output property named assessmentUserId from the results of other API methods such as GET peopleandjobs or GET behavioralassessments, etc.
  • Control whether and how the PI system notifies the Assessment Taker via email
    • notifyAssessmentAvailableUsingEmail- 0 (No - default) or 1 (Yes) - If you wish the PI system to notify the user of the assessment, you may also wish to provide an email subject and introductory body content using the following two parameters:
    • subject(optional) - email subject line to be used instead of the default value defined in the PI account settings.
    • message(optional) - introduction shown at the very beginning of the email message body to be used instead of the default value defined in the PI account settings.
  • Override the Assessment Owner and Contact Info - Assessments ordered via the API are automatically "owned" by the user account whose API Key is in use for the integration. See Generating an API Key for more details. The first and last name, email address, and phone of that user are the default person shown in the invitation email and assessment website as the contact point if assessment takers have any questions. That person is also shown as being responsible for the assessment when displayed in the PI software. If you wish to attribute the assessment to a different person -- a recruiter or hiring coordinator, for example -- you must specify any parameters you wish to be used in place of the default settings:
    • administeredByFirstName, administeredByLastName
    • administeredByEmail - must be used along with name parameters
    • administeredByPhone- optional
  • Actions to Perform After Assessment
    • assessmentStatusWebHook (optional) - define a listener URL on your integration system that will expect a POST of several attributes for each status change for a given assessment. Use this to signal your integration that the assessment is complete and ready for results to be read from the PI system. The attributes sent include assessmentId, externalId, assessmentState, and assessmentSource. See Assessment Status WebHooks for details
    • notifyAssessmentAvailableUsingEmail (optional) - use this to cause the PI system to send an email invitation to the assessment taker containing a link to the assessment and instructions. This notification message is sent using default subject and introductory message text as defined in the client settings in the PI software unless you also specify the following override parameters:
      • subject
      • message
    • autoSendPIReportToAssessmentTaker (optional) - 0 (default) = No, 1 = Yes. Some clients wish to send a copy of the assessment results report directly to the assessment taker.
    • sendCognitiveAssessmentOnCompletion(optional) - 0 (default) = No, 1 = Yes. If you wish to have your assessment taker take both Behavioral and Cognitive assessments, pass this parameter in POST behavioralassessments to automatically trigger the sending of a Cognitive assessment email invitation after the assessment taker completes the Behavioral assessment. This parameter is only available in the POST behavioralassessment method.
    • redirectURL (optional) - a web address to which the assessment taker's browser should be redirected after completing the assessment. This can be used, for example, to show the user a web page explaining next steps. Or if the assessment is being presented to the assessment taker as part of the application process, a redirect might be used to take the user back to the next stage of the online application.
  • Other Properties
    • externalId (optional) - This field provides an opportunity to store a unique identifier with the assessment being ordered up to 71 characters in length. This is different from externalPersonId mentioned above which is associated with the person. If an externalId is defined for an assessment and an assessmentStatusWebHook has been defined, this value is included in the POST variables sent by the PI system to the listener.
    • folderPath or folderGuid (optional) - The PI system always stores assessment takers into a folder within a structure controlled by the client. The default folder is determined on a client account level, and can be overridden by a setting in the user account who owns the API Key. Those folder settings are ignored if a different folder is specified using folder-related parameters. Since permissions can be attached to folders by client admins, the owner of the API Key used by the integration must have sufficient permissions to access the specified folder. There are two ways to specify a folder into which an assessment taker should be placed, but you can only specify one or the other of these two:
      • folderPath - a full path to the folder as displayed in the details area of the chosen folder witin the PI system settings. Backslashes in the path must be doubled to escape them for use in JSON: "\\Example Company\\Some Folder"
      • folderGuid - the PI system GUID for the given folder. This parameter may be used to avoid errors caused by spelling changes in the folder names.
    • languageLocale (optional) - PI system will assume that the language for assessments is the same as the default language for the client account. Possible language codes are found here: API Guide - Common
    • customInfo (optional) - an array of fieldName and fieldValue pairs containing any values you choose. WARNING: These fields are deprecated and may not be supported in future versions of the PI software and API.

2a. PI Sending Email

If you want PI to send email to the user, set the optional parameter notifyAssessmentAvailableUsingEmail to 1. The PI system will send an invitation message to the assessment taker including optional client-specified introductory message, standard instructions, contact information for the person responsible for the assessment, a link to the assessment.

2b. ATS Sending Email

If you want the ATS to send email to the user, set the optional parameter notifyAssessmentAvailableUsingEmail to 0 or omit it. The PI system will NOT send an invitation message to the assessment taker. The responsibility to show the assessmentUrl link to the assessment taker falls on the integration and the ATS. This can be included in an email message or in a web page shown to the user, or both. 

Example using CURL (line breaks added):
curl -X POST
 --header 'Content-Type: application/json'
 --header 'Accept: application/json' --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 -d '{ \ 
   "firstName": "Kim", \ 
   "lastName": "Prospect", \ 
   "email": "kim.prospect%40gmail.com", \ 
   "subject": "ACME Corp - Please take Behavioral Assessment", \ 
   "message": "As a part of your job application process, ACME Corp would like you to take this brief assessment to help complete our understanding of you! It only takes about 8 minutes.", \ 
   "administeredByEmail": "trecruiter%40acme.com", \ 
   "administeredByPhone": "800-555-1212", \ 
   "administeredByFirstName": "Terry", \ 
   "administeredByLastName": "Recruiter", \ 
   "associatedPositionTitle": "Sales Manager", \ 
   "gender": "Female", \ 
   "personType": "Candidate", \ 
   "notifyAssessmentAvailableUsingEmail": 1, \ 
   "externalId": "A123456", \ 
   "externalPersonId": "P345678", \ 
   "languageLocale": "en-US", \
   "assessmentStatusWebHook": "https://someintegrationserver.com/listener/pi-assessment", \
   "redirectURL": "http://acme.com/careers/next-steps", \ 
   "autoSendPIReportToAssessmentTaker": 1  \ 
 }' 
'https://pi.predictiveindex.com/api/v1/behavioralassessments'

Example of Response (HTTP response code 201):

{
  "errorResponse": null,
  "assessmentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "firstName": "Kim",
  "middleName": null,
  "lastName": "Prospect",
  "email": "kim.prospect@gmail.com",
  "impression": 0,
  "subject": "ACME Corp - Please take Behavioral Assessment",
  "message": "As a part of your job application process, ACME Corp would like you to take this brief assessment to help complete our understanding of you! It only takes about 8 minutes.",
  "assessmentDateTime": "2018-08-15T19:49:27.6886775Z",
  "expirationDateTime": "2018-08-23T12:00:00.0000000Z",
  "assessmentCompletedDateTime": null,
  "administeredByEmail": "trecruiter@acme.com",
  "administeredByPhone": "800-555-1212",
  "administeredByFirstName": "Terry",
  "administeredByLastName": "Recruiter",
  "scoringMethod": 1,
  "patternNumber": null,
  "descriptiveReportUrl": "",
  "associatedPositionTitle": "Marketing Director",
  "associatedPositionImageUrl": "/0?format=PNG",
  "folderId": null,
  "folderPath": "\\ACME Corp\\Candidates",
  "patternFullUrl": "",
  "patternSelfUrl": "",
  "gender": 2,
  "personType": "Candidate",
  "isDeleted": 0,
  "assessmentState": 10,
  "assessmentStatusWebHook": "https://someintegrationserver.com/listener/pi-assessment",
  "notifyAssessmentAvailableUsingEmail": 1,
  "externalId": "A123456",
  "externalPersonId": "P345678",
  "assessmentUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "assessmentUrl": "https://assess.predictiveindex.com/Account/LoginPi?a=XXXXXXXX8igigYxTzbfZQzR3Eeq2vrjn3xg2EesVjZuRWLScteGbnQQNVyKa20Kn&lang=en-US",
  "assessmentPassword": "XXXXXXXX",
  "descriptiveReportPageUrl": "",
  "personPageUrl": "https://pi.predictiveindex.com/Browse/PersonDetails?assessmentUserId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "redirectURL": "http://acme.com/careers/next-steps",
  "selfSigmaScore": null,
  "selfConceptSigmaScore": null,
  "synthesisSigmaScore": null,
  "positionSigmaScore": null,
  "customFields": null,
  "customReports": null,
  "latestWebhookStatus": null,
  "autoSendPIReportToAssessmentTaker": 1,
  "sendCognitiveAssessmentOnCompletion": 0
}
        

3. ATS Integration Receives Response from POST

The response to the POST behavioralassessments and POST cognitiveassessments methods includes all the parameter values passed in the call along with several useful properties that can be stored or used immediately. Of particular note are the following:
  • assessmentUrl - the link URL for the assessment to be taken. This is included in the email sent from PI if that option is chosen. It can be used to display to the assessment taker or included in an email sent from the ATS software. It may also be stored in the ATS for use in recovering from a lost invitation email, though the link will not function after the assessment is completed.
  • assessmentId - the internal PI reference to the newly created assessment. The integration logic may store this value for troubleshooting or future API calls.
  • personPageUrl - the web address of the Person Detail page for the newly created or referenced PI person. Before the assessment is complete, this page will show the current assessment status. After the assessment is complete, results can be found here. This is the most commonly stored URL for candidates in ATS data.
  • descriptiveReportPageUrl - the web address of the Report for this assessment. It is useful only after the assessment is complete and can also be reached from the personPageUrl location.
  • See thePOST behavioralassessments API Referencefor additional response properties.

4. Candidate Receives Assessment Email

Self explanatory.

5. Candidate Follows Link and Takes PI Assessment

Self explanatory.

6. Assessment End

Upon completing the assessment, an email is sent to both the assessment taker's email address and to the assessment administrator -- either the owner of the API Key used in the integration or the recipient specified by the optional administeredByEmailproperty, as well as any of the optional Actions to Perform After Assessment(explained in an earlier section) arecarried out.

7. PI Optionally Calls ATS Integration Assessment Status Webhook Listener

If the assessment order was placed with an assessmentStatusWebHook URL defined, the webhook listener can take the values received from the PI call and perform appropriate action. 

If the assessmentStatus is 40 (Complete), the next step would be to use the assessmentId in a call to GET behavioralassessments/{id} and possibly other methods to obtain all result details, as described in Part B:

Part B - Obtain Assessment Results Link to Additional Results

Diagram B:

/developers/s/APIRetrieveResults-Link.png?v=1

1. Obtain Assessment Results (GET)

The most common action to take upon receiving notification via webhook listener (or any other means) is to retrieve complete results from the PI system and store them into the ATS system. The methods used to obtain the results of an assessment must match the assessment type:
For example, if your integration of both Behavioral and Cognitive assessments into your ATS relies on two custom fields named pi_assessmentid_ba and pi_assessmentid_ca, you would look up the incoming assessmentId from the webhook call against these two fields to determine which candidate's results are ready to retrieve. With this knowledge, you would compose the appropriate API method call. For example:

curl -X GET
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
'https://pi.predictiveindex.com/api/v1/behavioralassessments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

2. Receive and Store Assessment Details

This stage of the integration can vary quite widely depending on the features supported by the ATS system that is the target of storing assessment results. Some ATS systems support an unlimited number of custom attributes including links and file attachments, while other ATS systems only support a narrowly defined assessment result that may include only a status, a score, and a link, for example.

Behavioral Assessment Results - GET behavioralassessments/{id}

Some of the most common Behavioral assessment result properties used by client integrations include:
  • assessmentStatus - this numerical value is usually converted into some text string that makes sense to end users, such as "Sent" or "Complete". The meanings of these numbers is defined here: API Guide - Common
  • personPageUrl - this is a web browser-friendly URL pointing to the PI software page which contains everything known about the assessment taker including results and reports. If nothing else is stored in the ATS as an assessment result, this link is probably the most useful item. Keep in mind that any link pointing to the PI software will require the user to log into the PI system. If your ATS users are not in possession of PI software user credentials, this will not work for those users. So you must either grant them PI software access or use another method of making PI results available, described below.
  • descriptiveReportPageUrl - this is a web browser-friendly URL pointing to the PI software page containing the Behavioral Report for the assessment taker. This is probably the second most valuable link (after personPageUrl) to display for users. Clicking this link does not immediately show a PDF Report, however. 
  • descriptiveReportUrl - this is an API method call, NOT a web browser-friendly link. You cannot simply display this link and expect users to click on it. Instead, you can use this link to make a secondary API method call which will return as a result the actual Behavioral Report PDF file. If you call this URL as it is delivered in the response property, you will get a response of a ZIP file containing two reports using Male and Female pronouns. In most cases, it is more convenient to your end users if you obtain a single PDF file, even if you have to use a default gender pronoun selection. (NOTE: gender-neutral reports are coming!) To get a single PDF file as a response, you must add a gender parameter to specify the pronouns to use.   
    https://pi.predictiveindex.com/api/v1/behavioralassessments/{id}/1?format=PDF&gender=Female
    You must also choose how to deliver this PDF file. There are two general strategies used: 
    • Store PDF in ATS - some ATS systems support attaching files to the candidate profile or the assessment results data structures. This is probably the most desirable because it avoids reliance on the integration and creates a more instantaneous and permanent access opportunity.
    • Stream PDF from PI to Browser - if the ATS system cannot allow PDF file upload, you can construct a web request handler in your integration solution that will take GET requests coming from a link you build and insert into the ATS data/UI which convert the request into an API method call that gets the PDF and streams it back to the browser. In this way, the end-user clicks a link and a PDF file pops up. This solution may be slower than storing the PDF file in the ATS system, but it makes report results available without the user having to log into PI and requires zero file storage in the ATS.
  • Also see the notes below in Downloading Reports regarding multiple methods available to download reports in PDF format.
Example using CURL (line breaks added):
curl -X GET
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 'https://pi.predictiveindex.com/api/v1/behavioralassessments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'


Reference Pattern Details - GET behavioralassessments/{id}/guidebook

This method call takes the same assessmentId as the GET behavioralassessments/{id}, but it returns all the descriptive language used to educate other people about the behavioral characteristics of that individual. Depending on the application you have in mind, you may find many of these response properties to be interesting. For example:
  • referencePattern/name, /description, /traits - these are good summary facts to display for an assessment taker
Example using CURL (line breaks added):
curl -X GET
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 'https://pi.predictiveindex.com/api/v2/behavioralassessments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/guidebook?languageLocale=en-US'


Cognitive Assessment Results - GET cognitiveassessments/{id}

Since the Cognitive Assessment provides a simple score, there are fewer result types typically stored in an ATS based on the results. 
  • assessmentState - like the Behavioral assessment, displaying the current status of the assessment is often desirable. Be sure to convert numeric values into something human readable. The meanings of these numbers is defined here:API Guide - Common
  • score - the value from 100 to 450 representing the assessment score - this is the score displayed within the PI software as the Cognitive score and in Cognitive reports
  • correct- the value from 0 to 50 representing the number of questions answered correctly out of 50 
  • percentileRank - a value from 1 to 100 representing the estimated position in the population of assessment takers with 1 being the lowest score and 100 being the highest score. A score of 92 indicates that 92% of assessment takers score the same as or lower than this result.
  • descriptiveReportUrl - an API method call URL that can be used to retrieve the PDF report file for this cognitive result. See the comments regarding options for handling the Behavioral assessment result property of the same name, above. 
Also see the notes below in Downloading Reports regarding multiple methods available to download reports in PDF format.
Some clients feel that Cognitive results are considered to be more sensitive than behavioral results and so they do not display scores or percentiles in places that are accessible to all users of the ATS system. If the ATS system does not support variation in the privacy level of custom assessment result fields, then it may be necessary to only store and display a Cognitive Job Match Score, as described below.

Example using CURL (line breaks added):
curl -X GET
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 'https://pi.predictiveindex.com/api/v2/cognitiveassessments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Job Match Score - GET persons/{id}

This method call takes the assessmentUserId property as a parameter. This can be found in any of the GET behavioralassessments results. Using this method will return some results that may also be useful to push into the ATS data for the candidate. If the PI account utilizes Job Target features and the integration is assigning associatedPositionTitle parameters during the POST behavioralassessments method call, the results of this method call will include these Job Match Score properties:
  • behavioralJobFitScore - a whole number 1-10 representing the strength of the match to the target pattern
  • cognitiveJobFitScore - a whole number 1-10 representing the strength of the match to the target score
  • combinedJobFitScore - a floating point value from 1-10 representing the combination of the other two scores using the weighting factor defined in the PI software. Example: 5, 7.5, 8.25, or 9
Example using CURL (line breaks added):
curl -X GET --header 'Accept: application/json' --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' 'https://pi.predictiveindex.com/api/v1/persons/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Downloading Reports

There are two general approaches to downloading reports available in the API, each reflecting a different API philosophy: 
  • *assessmentsmethod reports (using GET)
  • personsmethod reports (using POST)
The latter approach represents the future development path, so if you must choose, it is best to choose the report methods that rely on the persons API. Here are examples of the two methods available:

The persons API methods use POST so that a JSON array of person identifiers and other parameters can be passed in the body content.

Note: The Cognitive Report available through the persons API has the option of hiding job target information by using a new "showSensitiveInformation" body parameter. If set to false, the job target will be omitted, making the report eligible to be shared with an assessment taker. For example:
curl -X POST  --header 'Content-Type: application/json' 
  --header 'Accept: application/zip' 
  --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'  -d '{ \ 
   "reportLanguage": "en-US", \ 
   "personsToReportOn": [ \ 
     "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ 
   ], \ 
   "showSensitiveInformation": false \ 
 }' 'https://pi.predictiveindex.com/api/v3/persons/DownloadCognitiveReports'

Job Interview Guide - POST persons/DownloadInterviewGuide

When a person has completed the Behavioral Assessment and has an associatedPositionTitle defined, it is possible to request an Interview Guide. This Guide contains questions specifically tailored to uncover a better understanding of the match between the candidate's behavioral pattern and the job for which they are applying. 

The method requires that you pass as JSON parameters in the POST body the personId, jobId, and guideLanguage. You can get the personId from the assessmentUserId value in many response objects, and get the jobId from GET PeopleAndJobs/{id} method call results jobInformation/id.

Example using CURL (line breaks added):
curl -X GET
 --header 'Accept: application/json'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 'https://pi.predictiveindex.com/api/v2/peopleandjobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

From a developer standpoint, it may seem somewhat unusual for a POST to be used to obtain a download file, but it does work. You must handle the response stream as a file. 

Example using CURL (line breaks added):
curl -X POST 
 --header 'Content-Type: application/json'
 --header 'Accept: application/pdf'
 --header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
 -d '{ \
   "personId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", \ 
   "jobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", \ 
   "guideLanguage": "en-US" \ 
 }' 
 'https://pi.predictiveindex.com/api/v3/persons/DownloadInterviewGuide'

3. Assessment Details Link Displayed

If the ATS supports the storage of links to results in the PI software, then displaying the value of personPageUrl from GET behavioralassessments/{id} is the ideal value to display in that ATS user interface. That page organizes in one place all that is known about a given assessment taker. NOTE: Accessing the page requires that the user is able to  authenticate (log in) to the PI software.

4. Recruiter Follows Link

When displaying the link above, you may wish to mark up the link using target="_blank" so that clicking the link will open the PI software page in a new window/tab.

5. Recruiter Views Assessment Details Page

The link will lead to the PI software, requiring the user to log in if they are not already logged in.

If you wish to provide PI results to users of the ATS software without requiring a login to PI software, then you may wish to pursue placing other kinds of results data into the ATS system directly as described in step 2 above.