API Parameters
This PI platform API methods often utilize optional parameters, especially for those that return multiple items.
OData Parameters for Filtering, Searching, Ordering and More
Some common OData featuresare 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 Testingpage. 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
TIP: Be sure to completely test all OData features you intend to use with your integration. Not all methods and properties have implemented all the same OData support. If you find a method or property for which you would like to have OData support, contact the Integrations Teamand ask for an enhancement.GET https://pi.predictiveindex.com/api/v2/behavioralassessments?$filter=assessmentUser%2FexternalPersonId%20eq%20'363534'
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/v3/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/v3/jobs?$skip=0 - this returns the first 50 jobs
GET /api/v3/jobs?$skip=50 - this returns the next 50 jobs starting at 51
GET /api/v3/jobs?$skip=100 - this returns the next 50 jobs starting at 101
It is also advisable with methods like the GET /api/v3/jobs to use the $orderby parameter to sort the results into alphabetical order, like this:
GET /api/v3/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/v3/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.
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/v3/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/v3/jobs?$skip=0 - this returns the first 50 jobs
GET /api/v3/jobs?$skip=50 - this returns the next 50 jobs starting at 51
GET /api/v3/jobs?$skip=100 - this returns the next 50 jobs starting at 101
It is also advisable with methods like the GET /api/v3/jobs to use the $orderby parameter to sort the results into alphabetical order, like this:
GET /api/v3/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/v3/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.
