API Guide and ‘Try It’ functionality

Above is a list of all of the API classes that you can utilize with the Predictive Index software. If you click into a class, you will see details for the individual API methods within each class that perform specific actions as well as details of the available parameters with each API method.  

Performing Testing

The ‘Try it’ button listed with each API method will pop up a window allowing you to submit whatever request is being shown with the parameters you may have filled in, and the results will be displayed at the bottom of the window. The following sections will appear after you submit a request:

• HTTP Request - Shows the complete URL of the HTTP request for the action taken by the ‘Try it’ button. Can be changed to other formats such as curl in the dropdown.

• Response Body (if applicable) - the JSON response content, if any, returned by the API after using the ‘Try it’ button. 

• HTTP Response - The HTTP headers included in the response and the HTTP response code returned by the API after using the ‘Try it’ button. Success response codes are in the 200 range. 400 or higher is an error.

  • TIP: You should make intentional mistakes and see what error messages are shown here when you do.

In order to utilize the ‘Try it’ functionality, you must enter your API Key as well as any required parameters before hitting the ‘Send’ button as shown below.

API Key Management

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:

OData Parameters for 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 Examples page. The parameters often supported include:

• $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.

Working with Multiple Item Responses

All API methods that return multiple items in their results are limited to a maximum of 50 items per request. You can control the number of records returned by using the $top=XX parameter, but the highest number you can specify is 50, the default. You can omit the $top=50 if you want the maximum/default of 50. Retrieving all results will involve the use of the $skip parameter to loop through a result set and retrieve multiple sets of items, increasing the $skip amount with each call.

For example, to get all the jobs returned by GET /api/v1/jobs, you would use a looping construct to call it repeatedly using the $skip parameter to get groups of up to 50 items until no more results are obtained. The resulting calls would be something like this:

GET /api/v1/jobs?$skip=0 - this returns the first 50 jobs

GET /api/v1/jobs?$skip=50 - this returns the next 50 jobs starting at 51

GET /api/v1/jobs?$skip=100 - this returns the next 50 jobs starting at 101

It is also advisable with methods like the GET /api/v1/jobs to use the $orderby parameter to sort the results into alphabetical order, like this:

GET /api/v1/jobs?$orderby=name&$skip=50

From a programmer's perspective, here is representative looping code (without any error or request rate limit handling, not written in any actual language):

allItems[] = new array;

getResult[] = new array;

skipNum = 0;

while (skipNum == 0 || getResult[].Count > 49)

{

    getResult[] = GET /api/v1/jobs?$orderby=name&$skip={skipNum};

    if (getResult[].Any) { allItems[].Append(getResult[]);}

    skipNum = skipNum + 50;

}

// allItems[] now contains the full collection of jobs

Similar looping methods should be used with any of the other methods that return a JSON array of items.

Common Parameters / Objects / Enumerated Values

Assessment State/Status

The following statuses may be returned in the assessmentState property of any assessment-related API call (such as GET behavioralassessments. Only the Completed status is returned in the body of an assessmentStatusWebHook cal.:

• 10 - Sent

• 20 - Opened

• 30 - Started

• 40 - Completed

• 50 - Expired

• 60 - Failed

• 65 - Aborted

Gender

Although the Predictive Index platform does not require or offer to collect gender information for all supported languages, the following values may be returned in the gender property of any assessment-related API call (such as GET behavioralassessments), as described below:

• 0 - Unknown / Unspecified

• 1 - Male

• 2 - Female

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"

Behavioral Pattern Reference Profiles

There are 17 general behavioral pattern clusters known as "Reference Profiles" identified in the Predictive Index Behavioral Assessment results. 

Learn about Reference Profiles here: https://www.predictiveindex.com/reference-profiles

The 17 reference profile names and descriptions are as follows:

referenceProfileName

Reference Profile Description

referenceProfileNumber

Sigma Score Array

The values in the API results properties using names like aSigma or bSigma correspond to the distance in Sigmas from the Midpoint of the Behavioral Assessment graph.  Values are rounded to the tenth or hundredth of a Sigma.

Examples:

• "1.0" indicates the factor is 1 Sigma to the right (High) of the Midpoint

• "-0.5" indicates the factor is 1/2 Sigma to the left (Low) of the Midpoint

• "0.6" indicates the factor is 3/5 Sigma to the right (High) of the Midpoint

Note: A trained PI Practitioner or Certified Partner should always be consulted when implementing the use of this data.

Language Locale

The property languageLocale specifies the locale of the language of the assessment based on RFC 5646 Language-Region format. Below are the supported language locales supported for taking the Behavioral Assessment, obtaining a Behavioral Report, taking the Cognitive Assessment, and obtaining a Cognitive Report. The list of language locales available for other reports or assessments is a subset of these below, using the same codes when available. To learn which language locales are available for other reports or assessments, it is best to look at the Predictive Index software settings user interface controls to get the most accurate current list.