Common Parameters / Objects

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

Assessment Statuses

The following statuses may be returned in the assessmentStatus 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

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 Reference Profiles

There are 17 general behavioral pattern clusters known as "reference profiles" identified in the Predictive Index Behavioral Assessment results. They are defined in this site: https://www.predictiveindex.com/reference-profiles

IMPORTANT NOTE: As a developer, you cannot use the patternNumber property to determine the reference profile -- there is not a strict 1-to-1 mapping relationship between them. Several patternNumbers are associated with more than one reference profile because the boundaries have been defined slightly differently. While historically Predictive Index used pattern numbers to classify various PI patterns, this practice is no longer being emphasized in favor of the 17 reference profiles.  

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 patternNumber!
NameDescriptionReference 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

languageLocale

Language locale of the language of the assessment based on RFC 5646 Language-Region format.  Below are the supported language locales in which the Behavioral Assessment may be taken. The list of language locales available for reporting is a subset of these below, using the same codes when available. To learn which language locales are available for reports, it is best to look at the Predictive Index software settings to get the most accurate current list.

LanguagelanguageLocaleLocalized Language

Afrikaans

af-ZA

Afrikaans

Albanian - Albania

sq-AL

Shqip

Arabic (International)

ar-XM

العربية

Armenian - Armenia

hy-AM

հայերեն

Basque

eu-ES

Euskara

Bengali (India)

bn-IN

বাংলা

Bulgarian

bg-BG

Български

Catalan

ca-ES

Català

Czech

cs-CZ

Ceština

Danish

da-DK

Dansk

English (US)

en-US

English

Estonian (Estonia)

et-EE

Eesti Keel

Finnish

fi-FI

Suomi

French - France

fr-FR

Français

German (Germany)

de-DE

Deutsch

Greek

el-GR

Ελληνικά

Haitian Creole

ht-HT

Kreyòl Ayisyen

Hebrew

he-IL

עברית

Hindi

hi-IN

हिंदी

Hungarian

hu-HU

Magyar

Icelandic

is-IS

Íslenska

Indonesian

id-ID

Indonesia

Italian (Italy)

it-IT

Italiano

Japanese

ja-JP

日本語

Korean

ko-KR

한국어

Latvian

lv-LV

Latviešu

Lithuanian

lt-LT

Lietuvių k

Malay(Malaysia)

ms-MY

Melayu

Norwegian (Bokmål)

nb-NO

Norsk

Papiamentu

pap-AW

Papiamentu

Polish

pl-PL

Polski

Portuguese - Portugal

pt-PT

Português

Romanian (Romania)

ro-RO

Română

Russian

ru-RU

Русский

Serbian (Cyrillic, Serbia)

sr-Cyrl-CS

Srpski

Croatian (Croatia)

hr-HR

Hrvatski

Slovak

sk-SK

Slovenčina

Slovenian

sl-SI

Slovensko

Spanish - Spain (Modern Sort)

es-ES

Español (Europeo)

Swedish

sv-SE

Svenska

Tamil

ta-IN

தமிழ்

Filipino

fil-PH

Tagalog

Thai

th-TH

ไทย

Turkish

tr-TR

Türkçe

Ukrainian

uk-UA

Українська

Vietnamese

vi-VN

Tiếng Việt

Chinese - Taiwan

zh-TW

繁體中文

Dutch - Netherlands

nl-NL

Nederlands

Chinese - People's Republic of China

zh-CN

简体中文

Spanish - Latin America

es-XL

Español (Latinoamérica)

Portuguese (Brazil)

pt-BR

Português (Brasil)

Myanmar (Burmese)

my-MM

မြန်မာ (Burmese)

Farsi

fa-IR

فارسی

Georgian

ka-GE

ქართული

Guajarati

gu-IN

ગુજરાતી

Ilocano

ilo-PH

Ilokano

Kazakh

kk-KZ

Қазақ тілі

Khmer

km-KH

ភាសាខ្មែរ

Lao

lo-LA

ພາສາລາວ

FYRO Macedonian

mk-MK

Македонски

Punjabi

pa-IN

ਪੰਜਾਬੀ

Samoan

sm-WS

Samoan

Sesotho

st-LS

Sesotho

Sinhalese - Sri Lanka

si-LK

සිංහල

Swahili

sw-KE

Swahili

Tongan

to-TO

Lea Faka-Tonga

Xhosa

xh-ZA

IsiXhosa

Zulu

zu-ZA

IsiZulu


sigmaScore Array

The values in the array correspond to the distance in Sigmas from the Midpoint of the Behavioral Assessment graph.  Values are rounded to the nearest tenth of 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
bSigmadecimalAdjusted Z value for the B Factor
cSigmadecimalAdjusted Z value for the C Factor
dSigmadecimalAdjusted Z value for the D Factor
eSigmadecimalAdjusted Z value for the E FactorSome 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 valueThis parameter is not included with Position scores.