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:

NameTypeOptionalDescription
candidate_evaluation_idstringrequiredThe evaluation_id that was provided by the partner when the candidate was submitted for evaluation

HTTP Headers:

NameValue
Content-Typeapplication/json
AuthorizationBearer XXXXXXXXXXXXXXXXXX

Request payload:

NameTypeOptionalDescription
statusstringrequired40 characters limit. The status of the test will be shown in Comeet. When the test is completed, the status should be completed
outcomestringrequiredOne of the following:
passed
review
failed

Applies when status is set to completed. See description above
scorenumberoptionalOverall score; A real number between 1 to 5, eg. 3.5
summarystringoptionalPlain text; 2000 characters limit
criteriaarrayoptionalArray of the criteria that were evaluated
criteria[].titlestringrequiredTitle of the criterion. Required only if the criteria array is included
criteria[].notesstringoptionalPlain text; 500 characters limit
criteria[].scorenumberoptionalScore for criterion; A real number between 1 to 5, eg. 3.5. When no value is passed - users will see "Not sure" for this criteria.
criteria[].groupstringoptionalUse this property to group criteria together, eg. Exercise 1, Exercise 2, Overview. Limited to 200 characters
url_for_usersstringoptionalURL that registered users can go to to see the completed test page in your app. It is recommended to provide both url_for_users and url_for_non_users
url_for_non_usersstringoptionalURL that non-registered users can go to to see the completed test page in your app. It is recommended to provide both url_for_users and url_for_non_users

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.

ErrorStatus code
Candidate was not found404
Candidate was deleted404
Candidate evaluation ID does not exist404
{  
  "status": 404,
  "message": "Candidate was not found"
}