POST /behavioralassessments
Creates a Behavioral Assessment invitation.
Request
POST https://pi.predictiveindex.com/api/v1/behavioralassessments
Path Parameters
Query Parameters
Request Body
Response
If successful, this method returns a 201 Created response code and the Behavioral Assessment object in the response body.
Response Body
| Parameter | Type | Value | Required | Notes |
| firstName | string | The assessment taker's first name | Required* | *If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null. |
| middleName | string | The 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 | string | The assessment taker's last name | Required* | *If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null. |
| string | The assessment taker's email address | Required* | *If re-assessing an existing person using an externalId or externalPersonId, this parameter must be either excluded, empty, or null. | |
| expirationDateTime | string | The expiration date/time of the assessment invitation | Optional |
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 | string | The first name of the person who administered the assessment | Optional |
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 assessment | Optional |
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 assessment | Optional |
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. |
| administeredByPhone | string | The phone number of the person who administered the assessment | Optional |
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. |
| associatedPositionTitle | string | The title of the position associated to the assessment | Optional | This value must match a Position name that already exists. |
| gender | number | The gender of the assessment taker | Optional |
Valid values: 0 = Unknown 1 = Male 2 = Female |
| personType | string | The type of the person of the assessment taker |
Optional |
Valid values (case-sensitive): Unknown Candidate Other Employee Former Employee |
| assessmentStatusWebHook | string | The complete path to the web-hook that will be called when the assessment is created or completed | Optional | The 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. |
| languageLocale | string | The Language the invitation will be sent in | Optional | The 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. |
| notifyAssessmentAvailableUsingEmail | number | Indicates if assessment taker will be notified via email upon creation of the assessment | Optional |
Valid values: 0 = Don't Notify 1 = Notify |
| externalId | string | This 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. |
| externalPersonId | string | This is a caller defined ID for the assessment taker that allows for convenient creation of new assessments for the same user | Optional | 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. |
| folderPath | string | The full folder path as displayed within the Admin > Folder Management view | Optional | Backslashes in the path must be doubled to escape them: "\\Example Company\\Some Folder" |
| redirectUrl | string | The 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" |
| customFields | array | An array of Custom Fields (Custom Field Name and Assigned Value) | Optional | If a Custom Field Name and/or Assigned Value is not valid, the request will be accepted, but the Custom Field will not be assigned. |
| Parameter | Type | Value | Notes |
| assessmentId | string | The 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 | string | The assessment taker's first name | |
| middleName | string | The assessment taker's middle name | |
| lastName | string | The assessment taker's last name | |
| string | The assessment taker's email address | ||
| expirationDateTime | string | The 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" |
| administeredByFirstName | string | The 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 |
|
| administeredByPhone | string | The phone number of the person who administered the assessment |
|
| associatedPositionTitle | string | The title of the position associated to the assessment |
|
| gender | number | The gender of the assessment taker |
Valid values: 0 = Unknown 1 = Male 2 = Female |
| personType | string | The type of the person of the assessment taker |
Valid values (case-sensitive): Unknown Candidate Other Employee Former Employee |
| assessmentStatusWebHook | string | The complete path to the web-hook that will be called when the assessment is created or completed |
|
| assessmentUrl | string | The complete path to the website that the assessment taker will use to complete the assessment including embedded credentials | |
| notifyAssessmentAvailableUsingEmail | number | Indicates if assessment taker will be notified via email upon creation of the assessment |
Valid values: 0 = Don't Notify 1 = Notify |
| externalId | string | This is a caller defined ID that allows for convenient lookups by an identifier generated by the callers system. | |
| externalPersonId | string | This is a caller defined ID for the assessment taker that allows for convenient creation of new assessments for the same user | |
| assessmentUserId | string | This is the system assigned ID for the assessment taker that allows for convenient creation of new assessments for the same user | |
| redirectUrl | string | The URL the assessment taker will be directed to after the assessment is completed. |
|
| selfSigmaScore | Sigma Array | Score representing the Self Graph. | Please refer to the Common page for more details. |
| selfConceptSigmaScore | Sigma Array | Score representing the Self Graph. | Please refer to the Common page for more details. |
| synthesisSigmaScore | Sigma Array | Score representing the Self Graph. | Please refer to the Common page for more details. |
| positionSigmaScore | Sigma Array | Score representing the Self Graph. | Please refer to the Common page for more details. |
| customFields | Array | An array of Custom Fields (Custom Field Name and Assigned Value) |
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"
"customFields": [
{
"fieldName": "Favorite Color",
"fieldValue": "Blue"
},
{
"fieldName": "Favorite ood",
"fieldValue": "Pizza"
}
]
}
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
"customFields": [
{
"fieldName": "Favorite Color",
"fieldValue": "Blue"
},
{
"fieldName": "Favorite Food",
"fieldValue": 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”
© Predictive Index