POST /behavioralassessments

Creates a Behavioral Assessment invitation.

Request

POST https://pi.predictiveindex.com/api/v1/behavioralassessments

Path Parameters

N/A

Query Parameters

N/A

Request Body

Response

If successful, this method returns a 201 Created response code and the Behavioral Assessment object in the response body.

Response Body

ParameterTypeValueRequiredNotes
firstName stringThe assessment taker's first nameRequired**If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null.
middleName stringThe assessment taker's middle name Optional**If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null.
lastName stringThe assessment taker's last nameRequired**If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null.
email stringThe assessment taker's email addressRequired**If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null.
expirationDateTimestringThe expiration date/time of the assessment invitationOptional

The date and time must be in UTC using the ISO 8601 standard and must be in the future. This parameter can be down to seven (7) decimal places of precision.

Examples: "2015-01-31" or "2015-01-31T23:59:59.0123456Z"

administeredByFirstName stringThe first name of the person who administered the assessmentOptional

If this parameter is included, the following are also required: administeredByLastName, administeredByEmail.

If these parameters are not included, the API User's account details will be used.

administeredByLastName string The last name of the person who administered the assessmentOptional

If this parameter is included, the following are also required: administeredByFirstName, administeredByEmail.

If these parameters are not included, the API User's account details will be used.

administeredByEmail string The email address of the person who administered the assessmentOptional

If this parameter is included, the following are also required: administeredByFirstName, administeredByLastName.

If these parameters are not included, the API User's account details will be used.

administeredByPhonestringThe phone number of the person who administered the assessmentOptional

If this parameter is included, the following are also required: administeredByFirstName, administeredByLastName, administeredByEmail.

If these parameters are not included, the API User's account details will be used.

associatedPositionTitlestringThe title of the position associated to the assessmentOptional This value must match a Position name that already exists.
gendernumberThe gender of the assessment takerOptional 

Valid values:

0 = Unknown

1 = Male

2 = Female

personTypestringThe type of the person of the assessment taker

Optional

Valid values (case-sensitive):

Unknown

Candidate

Other

Employee

Former Employee

assessmentStatusWebHookstringThe complete path to the web-hook that will be called when the assessment is created or completed OptionalThe assessmentId, assessmentState, assessmentSource, and, if provided by the caller when creating or updating the assessment, externalId  are sent to the WebHook URL via HTTP POST at the completion of the assessment. See Common for more details.
languageLocalestringThe Language the invitation will be sent inOptionalThe default is en-US (English), if no value is provided.  The assessment taker can select to complete the assessment in another language. See Common for more details. 
notifyAssessmentAvailableUsingEmailnumberIndicates if assessment taker will be notified via email upon creation of the assessmentOptional

Valid values:

0 = Don't Notify

1 = Notify

externalIdstringThis is a caller defined ID that allows for convenient lookups by an identifier generated by the callers system. Optional If this parameter value that matches an already existing person's assessmentId in the PI data, you must NOT include the firstName, lastName, middleName, or email parameters.  
externalPersonIdstringThis is a caller defined ID for the assessment taker that allows for convenient creation of new assessments for the same userOptional If this parameter value that matches an already existing externalPersonId in the PI data, you must NOT include the firstName, lastName, middleName, or email parameters.
folderPathstringThe full folder path as displayed within the Admin > Folder Management viewOptionalBackslashes in the path must be doubled to escape them: "\\Example Company\\Some Folder"
redirectUrlstringThe URL the assessment taker will be directed to after the assessment is completed.Optional

This URL must be the full path, include the protocol.

Valid: "http://www.predictiveindex.com"

Not valid: "www.predictiveindex.com"






ParameterTypeValueNotes
assessmentIdstringThe unique assessmentId for the assessment No assumptions as to the format of the string should be assumed as it can change from version to version.

IDs from previous versions will retain their value and structure.
firstName stringThe assessment taker's first name
middleName stringThe assessment taker's middle name 
lastName stringThe assessment taker's last name
email stringThe assessment taker's email address
expirationDateTimestringThe expiration date/time of the assessment invitation

The date and time is in UTC using the ISO 8601 standard.  This is down to seven (7) decimal places of precision.

Example: "2015-01-31T23:59:59.0123456Z"

administeredByFirstNamestringThe first name of the person who administered the assessment


administeredByLastName string The last name of the person who administered the assessment


administeredByEmail string The email address of the person who administered the assessment


administeredByPhonestringThe phone number of the person who administered the assessment


associatedPositionTitlestringThe title of the position associated to the assessment
gender numberThe gender of the assessment taker

Valid values:

0 = Unknown

1 = Male

2 = Female

personTypestringThe type of the person of the assessment taker

Valid values (case-sensitive):

Unknown

Candidate

Other

Employee

Former Employee

assessmentStatusWebHookstringThe complete path to the web-hook that will be called when the assessment is created or completed 
assessmentUrlstringThe complete path to the website that the assessment taker will use to complete the assessment including embedded credentials
notifyAssessmentAvailableUsingEmailnumberIndicates if assessment taker will be notified via email upon creation of the assessment

Valid values:

0 = Don't Notify

1 = Notify

externalId stringThis is a caller defined ID that allows for convenient lookups by an identifier generated by the callers system. 
externalPersonId stringThis is a caller defined ID for the assessment taker that allows for convenient creation of new assessments for the same user
assessmentUserIdstring This is the system assigned ID for the assessment taker that allows for convenient creation of new assessments for the same user
redirectUrlstringThe URL the assessment taker will be directed to after the assessment is completed.


selfSigmaScoreSigma ArrayScore representing the Self Graph.Please refer to the Common page for more details.
selfConceptSigmaScoreSigma ArrayScore representing the Self Graph.Please refer to the Common page for more details.
synthesisSigmaScoreSigma ArrayScore representing the Self Graph.Please refer to the Common page for more details.
positionSigmaScoreSigma ArrayScore representing the Self Graph.Please refer to the Common page for more details.



Example Request

curl -X POST https://pi.predictiveindex.com/api/v1/behavioralassessments \

   -H "api-key: 12345678-ABCD-EFGH-1234-ABCDEFGH1234" \

   -H "Content-Type: application/json" -d @body.json

Example Request Body (@body.json)

{

   "firstName": "Sam",

   "lastName": "Flynn",

   "email": "test@predictiveindex.com",

   "expirationDateTime": "2017-12-31",

   "administeredByEmail": "recruiter@predictiveindex.com",

   "administeredByPhone": "+1 781-235-8872",

   "administeredByFirstName": "Recruiter First",

   "administeredByLastName": "Recruiter Last",

   "gender": 1,

   "personType": "Candidate",

   "assessmentStatusWebHook": "https://my.predictiveindex.com/behavioralcomplete",

   "notifyAssessmentAvailableUsingEmail": 1,

   "externalId": "894ever-behavioral",

   "externalPersonId": "EightyNine4ever"


}

Example Response

{

   "assessmentId": "abcd6001-9t12-4d48-87dd-bb8ef85y3q94",

   "firstName": "Sam",

   "middleName": "Kevin",

   "lastName": "Flynn",

   "email": "test@predictiveindex.com",

   "assessmentDateTime": "2016-10-02T23:59:59.0123456Z",

   "expirationDateTime": "2017-12-31T23:59:59.0123456Z",

   "administeredByEmail": "recruiter@predictiveindex.com",

   "administeredByPhone": "+1 781-235-8872",

   "administeredByFirstName": "Recruiter First",

   "administeredByLastName": "Recruiter Last",

   "scoringMethod": 1,

   "patternNumber": null,

   "descriptiveReportUrl": "",

   "associatedPositionTitle": null,

   "associatedPositionImageUrl": "",

   "folderPath": "Finance",

   "patternFullUrl": "",

   "patternSelfUrl": "",

   "gender": 1,

   "personType": "Candidate",

   "isDeleted": 0,

   "assessmentState": 0,

   "assessmentStatusWebHook": "https://my.predictiveindex.com/behavioralcomplete",

   "notifyAssessmentAvailableUsingEmail": 1,

   "externalId": "894ever-behavioral",

   "externalPersonId": "EightyNine4ever",

   "assessmentUserId": "aaaabbbb-cccc-dddd-eeee-ffffgggghhhh",

   "assessmentUrl": "https://assess.piworldwide.com/Account/LoginPi?a=+HMLjoyelhDxk0Gg4UHaHY7C9r3T424079jdYgSotAFWlej6xJ126rIIN5iAffm7&lang=en-US",

   "assessmentPassword": "1234",

   "descriptiveReportPageUrl": "",

   "personPageUrl": "https://pi.predictiveindex.com/Browse/PersonDetails?assessmentUserId=aaaabbbb-cccc-dddd-eeee-ffffgggghhhh",

   "redirectUrl": null,

   "selfSigmaScore": null, 

   "selfConceptSigmaScore": null,

   "synthesisSigmaScore": null,

   "positionSigmaScore": null


}


Example Web Hook Notification Call (called after the assessment is completed)

curl -X POST https://my.predictiveindex.com/behavioralcomplete \

   -d “assessmentId=abcd6001-9t12-4d48-87dd-bb8ef85y3q94&assessmentState=40&externalId=894ever-behavioral”