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
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",
}
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.
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.
- eq = equals
- gt = greater than
- lt = less than
- le = less than or equal
- ge = greater than or equal
- 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.