2. Submit a Candidate for Evaluation

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_message property. 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