API Guide

REST API

At the most basic level, using the API means creating HTTP POST, GET, DELETE, and PATCH requests including a required authentication method, using various parameters specified either in the URL or the request body, and consuming the results. Request body parameters and results are typically in JSON (JavaScript Object Notation).

An integration will normally require the construction of a collection of listeners and other processes that accept HTTP requests from the Applicant Tracking System (ATS) or Human Resource Information System (HRIS) and translate them into method calls to the Predictive Index API.

Your specific implementation will depend on the tool or programming environment used to construct the integration components. The following notes describe the requirements that must be met in your implementation.

Authentication

The API Key must be included in the header of each HTTP request and is defined as follows:

Header KeyHeader ValueExample Value
api-keyAPI Key generated in PI User Management1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6

Input and Output Payload

Input and output payload are in standard JSON (JavaScript Object Notation) using the content type application/json

HTTP Response Codes

When an API method call is successful, the response will carry a normal HTTP response code in the normal success (200) range, typically 200 or 201.

When an API method call is not successful, the response will carry an HTTP response code that matches the type of error that was encountered, usually in the 400 or 500 range. If an non-success response code is returned, the response body will contain a JSON object with error details.

For example, if the API system is down for maintenance, a condition that must be included in your integration logic, the response code will be 503 and the response object will be:

{  "number" : 27, 
  "context": null, 
  "description": "The API is down for maintenance",    "parameterErrors": [] }

Request Rate Limits

The Predictive Index has not published a precise limit on the number of requests the API will allow per second, minute, hour or day, but if an excessive number of API requests are received from any given source during any one minute time period, an HTTP response code of 429 Too Many Requests may be returned. 

The appropriate handling of this response code is to perform an exponential back-off algorithm in which the failed request is repeated after waiting increasing periods of time until successful. For example, wait 1 second before trying again, and if unsuccessful repeat after waiting 2 seconds, then 4 seconds, then 8 seconds, etc, until a success response (or some response other than 429) is received, possibly up to a minute after the first 429 was received.

If an individual requester demonstrates a pattern of continuously overloading the API system, throttling limits may be instituted for that client which are more stringent than the general throttling limits in place for all.

Errors

Standard Error Response Format

The standard error response format consists of a JSON object as follows:

ParameterTypeValueNotes
descriptionstring A description of the error in en-us format.This is intended for developers to understand the high-level issue that occurred. It is not intended for end user consumption. 
parameterErrorsError Array

This contains a list of the input properties that violated the constraints of the request and a corresponding description of the constraint violation in en-US format.  In addition a numeric code is provided so the developer can tie the error to a specific human readable message suitable to display to the user.  See the specific resource for possible error values that can be returned.  See Error Array for array format.  See Error Numbers of general error list.

This is intended for developers to understand which input properties had an issue and what the issue was. It is not intended for end-user consumption.
number numberThe numeric error number associated with the parameter error A numeric code is provided so the developer can tie the error to a specific human-readable message suitable for display to the end-user 
contextstringRun-time information associated with the errorThis often contains run-time information associated with the error that can be useful in diagnosing the root cause. 

Error Array

This contains a list of the input properties that violated the constraints of the request and a corresponding description of the constraint violation in en-us format.  In addition a numeric code is provided so the developer can tie the error to a specific human readable message suitable to display to the user.  See the specific resource for possible error values that can be returned.

ParameterTypeValueNotes
numbernumberThe numeric error number associated with the parameter errorThis number can be used by the caller to provide a correlation to a human-readable error message in the
user interface if applicable.
descriptionstringA description of the error in en-us format.This description is used for internal developer debugging. If a translated error description is required
the developer can use the Number field and provide a correlation to a human-readable error message
in the user interface if applicable.
propertyNamestringThe property name of the parameter that has the errorThe property name of the parameter that has the error.
contextstringRun-time information associated with the errorThis often contains run-time information associated with the error that can be useful in diagnosing the root cause.


Example Error Response

{
  "parameterErrors": [ {
    "number": 2,
    "description": "Required parameter was not provided",
    "propertyName": "FirstName"
    } ],
  "number": 1,
  "description": "Input criteria was not valid",
  "context": null
}

Standard Error Numbers

This is the list of errors that can be returned in the standard-error-result payload described in the "Standard Error Response Format" section. It is a living table that is updated as new errors are defined in the code.

Error NumberDescriptionError TypeNotesAPI Version
0SuccessGeneralIndicates there were no errors.1
Required input criteria was not valid General See the detailed parameter error information in the ParameterErrors collection.
Required parameter was not provided Parameter This error indicates that the referenced property is required. 
Parameter value is out of range the valid values are from X to Y Parameter Here the X and Y are replaced with the suitable range of values for the parameter.
This parameter must be less than the parameter P Parameter This parameter P must be less than the parameter this error is associated with. P is replaced with the name of the parameter this parameter must be less than.
The end point could not be reached General Typically occurs if a web-hook URL is incorrect or the endpoint url specified can't be reached .
Internal error occurred General Occurs if there is some issue completing the request. This is an internal issue with the service. 
The entity could not be found General Occurs if the entity specified typically by an ID is not found.
 27The API is down for maintenanceGeneralIndicates the API system is temporarily unavailable while system upgrades or maintenance is taking place.


Date and Time

All date and time values are expressed in UTC using the ISO 8601 standard.

ISO 8601 date and time format

Example: "2015-01-31T23:59:59.0123456Z"


OData Filtering, Searching, Ordering and More

Some common OData features are supported in the API. This allows data to be filtered and sorted as needed, permitting complex data gathering. Be sure to URL Encode any values passed.

To determine which OData parameters are supported for which API methods, look for details in the Parameters sections of the methods shown in the API Reference and Testing page. The parameters often supported include:

  • $filter - restrict which items are returned using field names, comparison operators and conjunctions to build specific filter conditions
  • $select - specify which fields should be returned
  • $search - find text in text fields
  • searchfields - restrict the $search parameter to only certain fields (otherwise searches many text fields)
  • $orderby - specify the sort field, with optional DESC or ASC modifier
  • $skip - when returning results that exceed the maximum (usually 50 results), use this parameter to specify how many results to skip, in other words the result before the one you want to start with
  • $top - how many results to return, up to the maximum (usually 50 results), used in conjunction with $skip to get pages of results. Be sure to use $orderBy with $skip and $top so you get unique results.
The comparison operators supported include:
  • eq = equals
  • gt = greater than
  • lt = less than
  • le = less than or equal
  • ge = greater than or equal
Notes:
  • If a field is of type string, a string comparison will be used even if it contains numbers (e.g. '2' > '10')
  • JSON response data hierarchy can be specified by separating parent nodes from child nodes with a forward slash (e.g. assessmentUser/email)
  • The values of parameters should generally be URL Encoded (e.g. space = %20, @ = %40, / = %2F)
  • Enclose string field values in single quotes, but not integer field values

Example 1:Get the second set of 50 completed assessments in date order

GET https://pi.predictiveindex.com/api/v2/behavioralassessments?$filter=assessmentState%20eq%2040&$orderby=assessmentCompletedDateTime&$skip=50&$top=50

Example 2:Get an assessment using the assessment taker email

GET https://pi.predictiveindex.com/api/v2/behavioralassessments?$filter=assessmentUser%2Femail%20eq%20'someone%40somewhere.com'

Example 3:Get an assessment using the externalId from the ATS originally assigned during creation

GET https://pi.predictiveindex.com/api/v2/behavioralassessments?$filter=externalId%20eq%20'176088'

Example 4:Get an assessment using the externalPersonId from the ATS originally assigned during creation

GET https://pi.predictiveindex.com/api/v2/behavioralassessments?$filter=assessmentUser%2FexternalPersonId%20eq%20'363534'


Resources

This section describes the resources.  Review their individual pages for details on their supported HTTP Verbs, their input payload, output payload, and query parameters.  For additional details and to test these interfaces, use the API Reference and Testing Site.

/assessments

The assessments resource provides access to all supported assessments. An assessment represents the results of a scored assessment. This includes the user who took the assessment, and all of the related details associated with the assessment.

/behavioralassessments

The beahavioralassessments resource provides access to PI Behavioral Assessments only. A Behavioral Assessment represents the results of a scored Behavioral Assessment. This includes the user who took the assessment, and all of the related details associated with the assessment.

/analytics

The analytics resource generates an analytics report graph which is used to compare the Behavioral Assessment results of a group of individuals in order to identify similarities and differences.