Common Parameters / Objects

Below are common attributes, features, parameters and objects used in the APIs.

Assessment State/Status

The following statuses may be returned in the assessmentState property of any assessment-related API call (such as GET behavioralassessments) or in the body of an assessmentStatusWebHook call, as described below:

  • 10 - Sent
  • 20 - Opened
  • 30 - Started
  • 40 - Completed
  • 50 - Expired
  • 60 - Failed
  • 65 - Aborted

Assessment Status WebHooks

The assessmentStatusWebHook property section has been moved to its own article: Webhooks

Person Type

The following values may be returned in the personType property of any assessment-related API call (such as GET behavioralassessments), as described below:

  • 1 - Unknown
  • 2 - Other
  • 3 - Candidate
  • 4 - Employee
  • 5 - Former Employee

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

Candidate Impression

The candidate impression field aims to support a tentative overall impression. Although support for the use of the impression field is still not fully implemented in the PI software, the following values may be returned in the impression property of any assessment-related API response as described below:

  • 0 - Unset
  • 1 - Favorite
  • 2 - Rejected
Scoring Method 

There are several avenues by which assessments responses are collected in the PI platform. These are known internally as scoring methods. When this value appears in API results, this does not imply that scores are calculated differently based on each method (calculations are the same for all methods), but it only describes which mechanism was used to offer the assessment and collect responses:
  • 1 - Email Invitation sent to an individual assessment taker through the PI platform
  • 2 - Checklist - assessment administrator manually transcribes the written responses recorded by assessment taker on a printed assessment 
  • 3 - Open Invitation Link - a pre-configured, unique web link shared with assessment takers requiring them to enter their own name and email before completing the assessment via the PI Classic software - like #9
  • 4 - Datasheet - assessment administrator enters one or more assessments via the PI Classic software
  • 5 - Combined Pattern - legacy scoring method used to combine results across versions of the Behavioral assessment
  • 6 - Datasheet ScoreID - same as #4 except that assessment taker enters a Behavioral Score ID belonging to a previously completed assessment which copies previous responses into current assessment
  • 7 - Email Invitation ScoreID - same as #1 but using Behavioral Score ID to copy previous responses
  • 8 - Open Invitation ScoreID - same as #3 but using Behavioral Score ID to copy previous responses
  • 9 - Open Invitation 2.0 -  same as #3 but using new settings developed in the New PI Experience software

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 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 Team and ask for an enhancement.

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

IMPORTANT NOTE: Historically Predictive Index used pattern numbers to classify numerous PI pattern groupings. This practice is no longer being emphasized in favor of the smaller collection of 17 Reference Profiles. As a developer, you cannot use the originalPatternNumber property (sometimes named patternNumber) to determine the correct Reference Profile -- there is not a strict 1-to-1 mapping relationship between them. Several original patternNumbers are associated with more than one Reference Profile because the boundaries have been defined slightly differently. 

To obtain the reference profile name via the API, use one of the following two methods:

  • GET /api/v2/peopleandjobs/{assessmentUserId} - returns the reference profile name in property: referencePatternInformation/name
  • GET /api/v2/behavioralassessments/{assessmentId}/guidebook - returns the reference profile name in property: referencePattern/name
The 17 reference profile names and descriptions are as follows:
*NOTE: Reference Profile ID is similar to but not the same as the original patternNumber!
Reference Profile NameReference Profile DescriptionReference Profile ID*
AdapterFlexible and situational. Ability to work with different people and adjust style as needed. 0
VenturerSelf-starter, self-motivator, risk-taker with a goal-oriented mind. 8
StrategistResults-oriented, innovative, and analytical with a drive for change. 10
AnalyzerAnalytical and technical, strong drive for ownership and need for rules and structure. 12
ControllerFocused on quality outcomes and control over work. Analytical and technical. 14
SpecialistStructured, highly detailed. Reserved and analytical, while respecting authority. 20
ScholarThorough, careful, and structured. Authoritative and direct. Consistent follow up. 22
IndividualistHighly independent and persistent, while remaining results-oriented. 24
CaptainProblem-solver, risk-taker, self-starter. Drive to control big picture, independent. 26
MaverickRisk-taker and big picture thinker. Not afraid of taking action. 30
PersuaderPersuasive, risk-taker. Quick to connect and strong drive for results. 36
AltruistTeam player, fast pace, quick to connect. Drive to do things quickly and correctly. 46
CollaboratorA friendly, understanding, willing and patient team player. 54
PromoterCasual and uninhibited. A persuasive extrovert with a tendency for informality. 56
GuardianPrecise, structured, team player. Patient and consistent approach. 60
OperatorSteady, conscientious, and relaxed. Learns through repetition. 64
CraftsmanStructured, analytical, team player. Focused on detail and process. 70


Sigma Score Array

The values in the API results properties using names likeaSigma orbSigma 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.

ParameterTypeValueNotes
aSigmadecimalAdjusted Z value for the A Factor (Dominance)
bSigmadecimalAdjusted Z value for the B Factor (Extraversion)
cSigmadecimalAdjusted Z value for the C Factor (Patience)
dSigmadecimalAdjusted Z value for the D Factor (Formality)
eSigmadecimalAdjusted Z value for the E Factor (Objectivity)Some arrays may have a NULL value indicating that this parameter is not relevant for that array.

This parameter is not included with Position scores.
mScoreintegerThe M Score value indicating the number of responses chosenThis parameter is not included with Position scores.

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.


English NameLanguage LocaleLocal NameBehav. Assess.Behav. ReportCognitive Assess.Cognitive Report
Afrikaansaf-ZAAfrikaansTrueFalseTrueFalse
Albaniansq-ALShqipTrueFalseTrueFalse
Arabic (International)ar-XMالعربيةTrueFalseTrueFalse
Arabic (Gulf)ar-AEلعربيةFalseFalseTrueFalse
Armenianhy-AMհայերենTrueFalseTrueFalse
AzeriLt-az-AZazərbaycan diliFalseFalseTrueFalse
Basqueeu-ESEuskaraTrueFalseTrueFalse
Bulgarianbg-BGБългарскиTrueFalseTrueFalse
Catalanca-ESCatalàTrueFalseTrueFalse
Chinese (Simplified)zh-CN简体中文TrueTrueTrueTrue
Chinese (Traditional)zh-TW繁體中文TrueFalseTrueFalse
Croatianhr-HRHrvatskiTrueFalseTrueFalse
Czechcs-CZCeštinaTrueTrueTrueTrue
Danishda-DKDanskTrueTrueTrueTrue
Dutchnl-NLNederlandsTrueTrueTrueTrue
Englishen-USEnglishTrueTrueTrueTrue
Estonianet-EEEesti KeelTrueFalseTrueFalse
Farsifa-IRفارسیTrueFalseTrueFalse
Filipinofil-PHTagalogTrueFalseTrueFalse
Finnishfi-FISuomiTrueTrueTrueTrue
Flemishnl-BEVlaamsFalseFalseTrueFalse
Frenchfr-FRFrançaisTrueTrueTrueTrue
Georgianka-GEქართულიTrueFalseTrueFalse
Germande-DEDeutschTrueTrueTrueTrue
Greekel-GRΕλληνικάTrueFalseTrueFalse
Greenlandickl-GLKalaallisutTrueFalseFalseFalse
Guajaratigu-INગુજરાતીTrueFalseFalseFalse
Haitian Creoleht-HTKreyòl AyisyenTrueFalseFalseFalse
Hebrewhe-ILעבריתTrueFalseTrueFalse
Hindihi-INहिंदीTrueFalseTrueFalse
Hungarianhu-HUMagyarTrueTrueTrueTrue
Icelandicis-ISÍslenskaTrueFalseTrueFalse
Ilocanoilo-PHIlokanoTrueFalseFalseFalse
Indonesianid-IDBahasa IndonesiaTrueFalseTrueFalse
Italianit-ITItalianoTrueTrueTrueTrue
Japaneseja-JP日本語TrueTrueTrueTrue
Kazakhkk-KZҚазақ тіліTrueFalseTrueFalse
Khmerkm-KHភាសាខ្មែរTrueFalseTrueFalse
Koreanko-KR한국어TrueTrueTrueTrue
Laolo-LAພາສາລາວTrueFalseTrueFalse
Latvianlv-LVLatviešuTrueFalseTrueFalse
Lithuanianlt-LTLietuvių kTrueFalseTrueFalse
Macedonianmk-MKМакедонскиTrueFalseTrueFalse
Malayms-MYBahasa MelayuTrueFalseTrueFalse
Malayalamml-INമലയാളംTrueFalseTrueFalse
Norwegian (Bokmål)nb-NONorskTrueTrueTrueTrue
Papiamentupap-AWPapiamentuTrueFalseFalseFalse
Polishpl-PLPolskiTrueTrueTrueTrue
Portuguesept-PTPortuguêsTrueTrueTrueTrue
Portuguese (Brazil)pt-BRPortuguês (Brasil)TrueTrueTrueTrue
Punjabipa-INਪੰਜਾਬੀTrueFalseTrueFalse
Romanianro-RORomânăTrueTrueTrueTrue
Russianru-RUРусскийTrueTrueTrueTrue
Samoansm-WSSamoanTrueFalseFalseFalse
Serbian (Latin)sr-Cyrl-CSSrpski (Latinica)TrueFalseTrueFalse
Sesothost-LSSesothoTrueFalseFalseFalse
Sinhalesesi-LKසිංහලTrueFalseFalseFalse
Slovaksk-SKSlovenčinaTrueFalseTrueFalse
Sloveniansl-SISlovenskoTrueFalseTrueFalse
Spanish (Latin America)es-XLEspañol (Latinoamérica)TrueTrueFalseTrue
Spanish (Europe)es-ESEspañol (Europeo)TrueTrueTrueTrue
Swahilisw-KESwahiliTrueFalseTrueFalse
Swedishsv-SESvenskaTrueTrueTrueTrue
Tamilta-INதமிழ்TrueFalseTrueFalse
Thaith-THไทยTrueFalseTrueFalse
Tonganto-TOLea Faka-TongaTrueFalseFalseFalse
Turkishtr-TRTürkçeTrueFalseTrueFalse
Ukrainianuk-UAУкраїнськаTrueFalseTrueFalse
Urduur-PKاردوFalseFalseTrueFalse
Vietnamesevi-VNTiếng ViệtTrueFalseTrueFalse
Xhosaxh-ZAIsiXhosaTrueFalseTrueFalse
Zuluzu-ZAIsiZuluTrueFalseTrueFalse