Introduction

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

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

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

Getting Access - Become a Partner

  1. Submit the Become a Partner Form. You will be requested to submit the following information:
  • Your contact details - name, email, role and company name
  • Your app - name, description, website URL, logo (270 x 80 px) and avatar (80 x 80 px)
  • Service type – One of the following: Candidate assessment, Video interviews, Background checks, Reference checks, Other.
  • Endpoints – For the 3 webhooks.
  • Activation page - Instead of asking users to copy and paste the API Key, you can make activation easier for users by creating an activation page. See details below.
  • API Terms of Use - By using this API, you agree to the Comeet API Terms of Use.
  1. Once the submission is approved, we will send you your secret and invite you to your Sandbox account. Sign up to your Sandbox account and retrieve the API Key for that account from the integrations setting page.

  2. Develop the integration. When ready, send us a short video that demonstrates the integration including all the steps described in the Example Scenario below.

  3. We'll review the submitted video. Once approved, we'll provide you the secret to the production environment.

📘

Activation Page - Make activation easier for Comeet users

If you provided an activation url then the user will click on the Activate button in Comeet which will open the url you provided. The request will include the api-key of the Comeet account and the Signature that allows you to verify that the request was made by Comeet. Alternatively, if you don't provide the activation url the user will click on Copy Key and will manually input the API Key in your app (ie. by pasting in the product or sending to a support rep).

Authorization

All API calls use HTTPS and should be verified by your system:

  1. To verify a request you need these values:

    • secret - received when approved as a Comeet partner. See Getting Access - Become a Partner.
    • api-key - received from a Comeet customer when the integration is activated.
  2. Comeet will add the Authorization header to all HTTP requests using the following syntax:
    Authorization: Bearer <token>

  3. Verify the request by decoding the token with your secret using JWT. The result must be identical to the api-key. You can use one of the many JWT libraries available online.

Example Scenario

  1. Set up the integration
  • A Comeet user with an Admin role will find your service on Comeet's Integrations page and click Integrate.
  • The user will click on Copy Key and will manually input the API Key in your app (ie. by pasting it in your app or sending it to a support rep).
  1. Set up the test step on the position workflow
    The recruiter will add a step to the workflow and define it as a step that uses your app. Then the user will select one or more of the tests that your app provides. The user can also create the step’s policy; whether it will run automatically or require confirmation.

  2. Send test
    When a candidate reaches the test step, Comeet will initiate the request to submit the test for evaluation. If necessary, Comeet will send the candidate an email requesting completion of an evaluation test using a link provided by the evaluation partner.

  3. 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 outcome and policies defined by the recruiter or hiring manager, the candidate will progress in the workflow.

Deleting Candidate Data

Candidate data may be deleted or pseudonymized according to the company's data retention policy or following a request from a candidate. As part of your implementation of the Evaluation API, you must implement a mechanism to delete candidate data from your system when required. This is in accordance with Comeet's API Terms of Use.

To identify which candidate data to delete, use the GET deleted-candidates endpoint. Note that for evaluation integration, the proper endpoint to use in this case will be: https://api.comeet.co/evaluation/deleted-candidates.