3. Submit an Evaluation

🚧

Transition from the obsolete "Retrieve an Evaluation" webhook

The “Retrieve an Evaluation” webhook was replaced with the "Submit an Evaluation" endpoint. If your app is using the now obsolete "Retrieve an Evaluation" webhook, then you are required to transition before Dec 31 2023.
Transitioning to using this endpoint allows you you to update the status of the assessment in real time and reduce the load on your servers caused by the frequent requests to the “Retrieve an Evaluation” webhook.
After transitioning, notify us at [email protected] and we will set up your Evaluation app to stop making requests to the “Retrieve an Evaluation” endpoint.

Make a request to this endpoint to update the status and content of the evaluation.

Evaluation status

The status property allows you to update Comeet users about the status of the assessment throughout the process and indicate when it is completed.

• You can make multiple updates to indicate interim statuses until the assessment is completed, such as "Test started" (note that the status property has a 40 character limit). The provided status is shown to users on the candidate's workflow.
• When the assessment is completed, set the status to completed to complete the hiring step in the workflow. The provided outcome will define what happens next, see more information below.
• Once the status is set to completed then it cannot be changed again. You can, however, make additional requests to update the content of the evaluation.

Evaluation outcome

When the assessment is completed, the outcome property is presented to Comeet's users to indicate the result of the assessment as part of the candidate's Evaluation.

Your Evaluation App can be set up to always create a task for the relevant user to review the results of the evaluation or to enable candidate disposition based on the provided outcome.

When candidate disposition is enabled then following actions will take place based on the provided outcome:

• passed - the candidate will continue to the next step in the hiring process
• review - Comeet will create a task to review the results of the assessment
• failed - the candidate will be rejected

🚧

Handling edge cases

If the assessment could not be complete for any reason, make sure to complete the hiring step to allow the hiring process to continue. In such cases, provide a clear explanation to the user about what happened. For example, if the candidate did not complete the test and it expired, the submitted evaluation could be:
{
"status": "completed",
"outcome": "review",
"summary": "Test expired: The candidate did not complete the test within 7 days."
}

Request

POST https://api.comeet.co/evaluation/status?candidate_evaluation_id=[candidate_evaluation_id]

Query string params:

HTTP Headers:

Request payload:

Request example

POST https://api.comeet.co/evaluation/status?candidate_evaluation_id=000

{
    "status": "completed",
    "outcome": "passed",
    "score": 4.5,
    "summary": "Performed well.",      
    "criteria": [
        {
            "title": "Riding a Nimbus 2000",
            "notes": "Quidditch World Cup potential.",
            "score": 5
        },
        {
            "title": "Riding a Firebolt",
            "notes": "Impressive maneuvers.",
            "score": 4
        }      
    ],
    "url_for_users": "https://www.evaluation-partner.com/evaluation/1111",
    "url_for_non_users": "https://www.evaluation-partner.com/evaluation/1111?token=hgsadkf3kas56jdgfsdsakjpgdhqfjakansmgdhfrkj56as8h0gdu"      
}

Response

The response to a successful request is HTTP 204 with no content.

Errors

If you make an invalid request, you will receive a detailed error response with one of the following error codes.

{  
  "status": 404,
  "message": "Candidate was not found"
}