2. Submit a Candidate for Evaluation

Comeet 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

NameValue
Content-Typeapplication/json
AuthorizationBearer XXXXXXXXXXXXXXXXXXXXX

Payload

NameTypeOptionalDescription
test_idsarray[string]requiredArray of evaluation partner test_id. The array will only include one value
candidateobjectrequiredCandidate details
candidate.uidstringrequired
candidate.first_namestringrequired
candidate.middle_namestringoptional
candidate.last_namestringoptional by default. Please contact us if you wish to define as required
candidate.phonestringoptional by default. Please contact us if you wish to define as required
candidate.emailstringrequired by default. Please contact us if you wish to define as optional
candidate.resumeobjectoptional
candidate.resume.namestringoptionalFile name of the resume
candidate.resume.urlstringoptionalURL to the resume. The link expires 3 minutes after it was submitted
candidate.offers[]arrayoptionalIncluded if the Evaluation app has permission to access offer letters
candidate.offers[].urlstringoptionalURL 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}.
positionobjectrequiredThe position for which the candidate is being considered
position.uidstringrequired
position.namestringrequired
assigneesarrayrequiredThe users who are responsible for this step in the hiring process
assignees[].first_namestringrequired
assignees[].middle_namestringoptional
assignees[].last_namestringoptional
assignees[].emailstringrequired

📘

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.

NameTypeOptionalDescription
candidate_evaluation_idstringrequiredUnique 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