Recruit will make this request to your endpoint to submit a candidate for a test.
Request
The endpoint is defined by the evaluation partner.
POST https://www.evaluation-partner.com/api/tests/submit
HTTP Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer XXXXXXXXXXXXXXXXXXXXX |
Payload
| Name | Type | Optional | Description |
|---|---|---|---|
| test_ids | array[string] | required | Array of evaluation partner test_id. The array will only include one value |
| candidate | object | required | Candidate details |
| candidate.uid | string | required | |
| candidate.first_name | string | required | |
| candidate.middle_name | string | optional | |
| candidate.last_name | string | optional by default. Please contact us if you wish to define as required | |
| candidate.phone | string | optional by default. Please contact us if you wish to define as required | |
| candidate.email | string | required by default. Please contact us if you wish to define as optional | |
| candidate.resume | object | optional | |
| candidate.resume.name | string | optional | File name of the resume |
| candidate.resume.url | string | optional | URL to the resume. This link can only be used by a signed in user to view the resume in the browser |
| candidate.offers[] | array | optional | Included if the Evaluation app has permission to access offer letters |
| candidate.offers[].url | string | optional | URL to the PDF file of the offer letter, valid for 300 seconds. Authorization header is required as explained here. An unsigned offer letter will include the attributes {signature:employee} and {signature:employer}. |
| position | object | required | The position for which the candidate is being considered |
| position.uid | string | required | |
| position.name | string | required | |
| assignees | array | required | The users who are responsible for this step in the hiring process |
| assignees[].first_name | string | required | |
| assignees[].middle_name | string | optional | |
| assignees[].last_name | string | optional | |
| assignees[].email | string | required |
Required fields in the request
A few fields in the request can be customized per the evaluation partner's needs as required or optional. For example, if the candidate’s email is required for your service then it can be defined as required, preventing the user from submitting a candidate without an email address.
Request example
{
"test_ids": ["5354343", "4324343"],
"candidate":
{
"uid": "AAA.00",
"first_name": "Harry",
"middle_name": "James",
"last_name": "Potter",
"phone": "123-456-7890",
"email": "[email protected]",
"resume": {
"name": "harry_cv.pdf",
"url": "https://comeet.amazonaws.com/65c0a9ff2166g"
}
},
"position":
{
"uid":"87.405",
"name":"Account Executive"
},
"assignees": [
{
"first_name": "Cory",
"middle_name": "",
"last_name": "James",
"email": "[email protected]"
},
{
"first_name": "Collin",
"middle_name": "Charles",
"last_name": "Cha",
"email": "[email protected]"
}
]
}
Response
When a successful request is made, the response must include an object that includes the candidate_evluation_id property. This is a unique identifier that you define, which is subsequently used to update the status of the test and its evaluation.
| Name | Type | Optional | Description |
|---|---|---|---|
| candidate_evaluation_id | string | required | Unique ID of the candidate submission for requested tests |
Response example
{
"candidate_evaluation_id": "98765"
}
Handling errors
In case of an error, the response must include an object with the
display_messageproperty. This message will be displayed to the user to inform them about the nature of the error. Please make sure to write a meaningful description and that would be clear to the recruiter submitting the test, and provide a suggested next step for them to overcome the issue. See example