API Guide

The Predicitive Index offers access to software data and functionality through an Application Programming Interface (API) that relies on the REpresentational State Transfer (REST) model. At the most basic level, using a REST API means creating HTTP POST, GET, DELETE, and PATCH requests using various named methods including a required authentication header, using various parameters specified either in the URL or the request body, and doing something with the results. Request body parameters and results are expected in JSON (JavaScript Object Notation), and XML (Extensible Markup Language) format is not supported by this API.

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 logic will depend on your particular goals, the integration features of the other systems involved, and the tool or programming environment used to construct the integration components.

API Guide Sub-Pages

Common - A collection of properties, parameters, and other features that are used by many API methods
Webhooks - Explanation of the use of webhook signals to notify external system listeners of changes
Integration Best Practices - A detailed walk-through of the API methods, parameters, and properties used in the most common assessment integration use cases
API Reference Explained - Introduction to the public API reference site which can also be used for real-time testing
behavioralassessments - Detailed explanations of the parameters and properties for the API methods that manipulate Behavioral Assessments. Not all methods are represented in this section since 100% of methods are documented generally in the API Reference site above.

General REST API Requirements

The following notes describe the general 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 Key	Header Value	Example Value
api-key	API Key generated in PI User Management	1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6

Example CURL request (line breaks added):

curl -X GET 
--header 'Accept: application/json' 
--header 'api-key: 1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6'
'https://pi.predictiveindex.com/api/v2/behavioralassessments'

Input and Output Payload

Input parameters and output payload are in standard JSON (JavaScript Object Notation) using the content type application/json for all requests that don't return file objects such as images or reports.

Example CURL request (line breaks added):

curl -X POST 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'api-key: 1a2bc3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6' 
-d '{ \ 
   "firstName": "Test", \ 
   "lastName": "Person", \ 
   "email": "testperson%40mailinator.com", \ 
   "personType": "Candidate", \ 
   "notifyAssessmentAvailableUsingEmail": 1 \ 
 }' 
'https://pi.predictiveindex.com/api/v1/behavioralassessments'

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, 201 or 204.

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

Since October 2018, The Predictive Index has placed a limit on the approximate number of requests the API will allow per minute from any single source. If an excessive number of API requests are received during any one minute time period, an HTTP response code of 429 Too Many Requests may be returned. The term "approximate" is used here because of the nature of managing limits in a multiple-server environment. An actual limit is imposed on each server and the expected combined effect is a limit of approximately the number published. Each of 10 servers is limited to 10 requests per minute per server. If your application receives a message "API request exceeded 10 request per minute limit" then it represents response message from one server. In reality, your application exceeded the approximately 100 request limit from the 10 servers.

API request rate throttling limit: 100 requests per minute per API Key

The most 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, after getting a 429 response, wait 1 second and then try again, and if unsuccessful repeat after waiting 2 seconds, then 4 seconds, then 8 seconds, etc, until a success response is received, possibly up to a minute or more after the first 429 was received. It is best to implement this algorithm for all request types in case limits are reached due to the actions of one process that affect the requests of another process. The following 3rd party article provides a good explanation and code examples: https://cloud.google.com/iot/docs/how-tos/exponential-backoff.

If implementing an exponential back-off algorithm is too complex, it may be sufficient to put a pause of 1 or 2 seconds between requests that are generated by any looping process. This will ensure that high-volume processes do not contribute more than 30 to 60 requests per minute, leaving space within the limits for ad-hoc requests that may arise from low-volume processes.

In all cases, it is the responsibility of the integration developer to implement error-handling and notification mechanisms that will ensure that all exceptions are brought to the attention of the appropriate people for follow-up when necessary.

If an individual API request source 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:

Parameter	Type	Value	Notes
description	string	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.
parameterErrors	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. 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	number	The 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
context	string	Run-time information associated with the error	This 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.

Parameter	Type	Value	Notes
number	number	The numeric error number associated with the parameter error	This number can be used by the caller to provide a correlation to a human-readable error message in the user interface if applicable.
description	string	A 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.
propertyName	string	The property name of the parameter that has the error	The property name of the parameter that has the error.
context	string	Run-time information associated with the error	This 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 Number	Description	Error Type	Notes	API Version
0	Success	General	Indicates there were no errors.	1
1	Required input criteria was not valid	General	See the detailed parameter error information in the ParameterErrors collection.	1
2	Required parameter was not provided	Parameter	This error indicates that the referenced property is required.	1
3	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.	1
4	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.	1
5	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 .	1
6	Internal error occurred	General	Occurs if there is some issue completing the request. This is an internal issue with the service.	1
7	The entity could not be found	General	Occurs if the entity specified typically by an ID is not found.	1
27	The API is down for maintenance	General	Indicates 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'

TIP: Be sure to thoroughly test all OData features you intend to use. Not all features are supported in all methods and for all properties. If you find an unsupported method property that you would like to have supported via OData features, please send your request to integrations@predictiveindex.com.