Evaluation API

This API is for providers of recruiting tools that wish to offer their service to Comeet users. If you are interested please contact us at support@comeet.co.

Background

Comeet enables recruiters to automate their recruiting processes by creating workflows that are comprised of recruiting steps or tasks. These steps are either conducted in-house or by external recruiters or integrated recruiting tools. This article is intended for providers of recruiting tools that assess or evaluate candidates.

API Overview

The API works in the form of webhooks where Comeet performs HTTP requests to the service of the evaluation provider. Implementing the API requires the creation of these endpoints:

  1. Get list of tests
  2. Submit candidate for evaluation
  3. Get evaluation

Example Scenario

  1. Set up the integration
    This is a one-time setup. A Comeet user will find your service on our  Integrations page and click Activate. In case of a reseller partnership, the user is asked to approve purchase of the service. Otherwise, the user is asked to enter his/her Account identifier and Secret key that should be provided by your service.
  2. Set up the evaluation step on the position workflow
    The recruiter will add a step to the workflow and define it as a step of type: Evaluation app. Then the user will select one or more of the tests that your company provides with their description. The user can also set up the step’s policy; whether it is run automatically or requires confirmation, whether the candidate proceeds to the next step automatically, rejected or requires approval to progress in the recruiting process. Each setting can be configured  differently for each step at each position and can be changed (on-going).
  3. Send test
    When a candidate reaches the evaluation step, a candidate_test is created. If necessary, Comeet will send the candidate an email requesting to complete the test using a link given by the evaluation partner.
  4. Test is completed
    Comeet periodically checks on test status until it is completed. After completion, the evaluation is added to the candidate profile. Depending on the score and any policies defined by the recruiter or hiring manager the candidate will progress in the workflow.

Become a Comeet Evaluation Partner

If you are interested in offering your service to our customers, please contact us at support@comeet.co and introduce yourself.

Please send us the following information:

  • Endpoints – For the 3 webhooks;
  • Service type – One of the following: Candidate assessment, Video interviews, Background checks, Reference checks, Other;
  • Short description – For recruiters, up to 120 characters;
  • Logo – Horizontal – 270 x 80 px – featured on the Integrations page within Comeet;
  • Avatar – Square – 80 x 80 px – shown on the candidate’s workflow;
  • Guide – Best practices and FAQ to recruiters and hiring managers using Comeet;
  • Links to Your Privacy Policy and Terms of Use – When activating the integration for the first time, the recruiter is asked to accept the terms and conditions.

We will set up a Comeet sandbox account that you can use for testing. Let us know when the integration is ready for our review and testing. After approval, we will set the integration live for all customers.

Set Up an Organization

Evaluation providers should provide each organization (account) the following details:

Secret key – Used to generate a digital signature using the SHA256 algorithm on the sent data. The signature is included in the HTTP header signature allowing your service to verify Comeet as the sender.

Account identifier – Identifies the organization that uses the service.

Get List Of Tests

The list of tests is shown to the user who sets up the evaluation step as part of the position’s workflow. Each test may include a description.

In case of an error retrieving the list, the last list that was successfully retrieved will be used until the next successful response.

Request

Query string params:

NAME TYPE OPTIONAL DESCRIPTION
account String Required Account identifier of the organization
Sample Request
Response

Response is an array of tests.

NAME TYPE OPTIONAL DESCRIPTION
test_id  String  Required test id
test_name  String  Required Test name
test_description  String  Optional Test description in HTML, shouldn’t include inline styling, limited to 5000 characters.
Sample Response

Submit Candidate For Evaluation

Submit a candidate for one test or more. It is up to the evaluation provider to specify  whether Comeet should send a message to the candidate to complete the test at a specified link.

Optional customization, contact us to specify your preferences.

  • The evaluation partner can specify whether the request should allow multiple tests or only one test at a time.
  • The Optional / Required fields in the request can be customized per the evaluation partner needs. For example, if the candidate’s email is mandatory for the service then it can be defined as required, preventing the user from submitting a candidate who doesn’t have an email address defined.

In case of an error submitting a candidate for evaluation, the recruiter will be notified and requested to review the error message.

Request

Query string params:

NAME TYPE OPTIONAL DESCRIPTION
account  String  Required Account identifier of the organization

Payload:

NAME TYPE OPTIONAL DESCRIPTION
test_ids  Array of Strings Required Array of evaluation partner test_id
first_name  String Required
middle_name  String Optional
last_name  String Optional
phone  String Optional
email  String Optional
resume Object Optional
resume.name  String Optional  File name of the resume
resume.url  String Optional A URL to the resume. The link expires 3 minutes after it was submitted
Sample Request

Response
NAME TYPE OPTIONAL DESCRIPTION
candidate_evaluation_id  String Required Unique id of the candidate submission for requested tests
test_url_for_candidate  String Optional When provided Comeet will send an email message to the candidate requesting to complete the test at the specified URL
instructions_for_candidate  String Optional Plain text. Only applicable when test_url_for_candidate is provided. When provided, these instructions will be included as part of the message to the candidate.
Sample Response
 

Get Evaluation

This endpoint is used periodically to check the status of candidate tests. The provided status is shown to users within Comeet. After the test is reported as completed Comeet will stop checking the test’s status.

Request

Query string params:

NAME TYPE OPTIONAL DESCRIPTION
candidate_evaluation_id  String  Required candidate_evaluation_id that was previously  created
account  String  Required Account identifier of the organization
Sample Request
Response
NAME TYPE OPTIONAL DESCRIPTION
status  String  Required 25 characters limit. The status of the test will be shown in Comeet. When the test is completed, the status should be “Completed”
score  Number  Required  Number, integer between 0 to 100
evaluation  Array of Objects  Optional Details about the test and/or breakdown of the score
evaluation[].title String  Required Title of the attribute
evaluation[].notes String  Optional Plain text. 500 characters limit
evaluation[].score Number  Optional Score for skill, integer between 0 to 100
url_for_embedded_view  String  Optional This is useful when a special visual representation helps understand the test’s results. When provided, users will be able to see this document embedded in an iframe. The URL must include an access token and should always be available to all users. The page itself should display the evaluation results without identifying information about the candidate.
Sample Response
 

Errors

In case of an error that requires the user’s attention, the response should provide a message for the user that the describes the issue. In addition, it is strongly recommended to include technical information that will help understand the problem.

Sample Error Response
Have more questions? Contact us at support@comeet.co