As an assessment or background check provider, you want to reduce the friction for your customers to order assessments or background checks for their candidates. By building on top of Kombo’s Unified ATS Assessment & Background Check API, you can allow your customers to seamlessly start assessments or background checks right from their Applicant Tracking System (ATS). Here’s how it works:
  1. You submit your available packages to Kombo. We’ll take care of configuring them in your customer’s integration. Your customers can now submit assessment or background check orders from their ATS.
  2. When your customer triggers a new assessment or background check order in the ATS, Kombo sends you a webhook event, so you can automatically send out an email to the candidate and get the assessment or the background check process started.
  3. Once the candidate has completed the assessment or the background check, you send the results to Kombo. We then write them to the ATS system.
  4. Your customers can conveniently access the assessment or the background check results directly within their ATS.
Continue reading to learn more about what these steps look like in practice.

​
Setup: Connecting a new customer

Kombo Connect guides your customer through the process of connecting their ATS.

Use Kombo Connect to set up your integrations with your customers. We’ll guide your customers through the process of setting up their integrations.

​
1. Configuring available packages

Submit all your available assessment and/or background check packages for the customer to Kombo. Kombo automatically configures the ATS to surface the packages to your customer. 
curl --location --request PUT 'https://api.kombo.dev/v1/assessment/packages' \
  --header 'X-Integration-Id: smartrecruiters:example_integration_id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer example_kombo_token' \
  --data '{
    "packages": [
      {
        "id": "YOUR-PKG-ID-0001",
        "name": "Postgres",
        "type": "SKILLS_TEST",
        "description": "Postgres test description..."
      },
      {
        "id": "YOUR-PKG-ID-0002",
        "name": "Javascript",
        "type": "SKILLS_TEST",
        "description": "Javascript test description..."
      }
      {
        "id": "YOUR-PKG-ID-0003",
        "name": "Civil Records",
        "type": "BACKGROUND_CHECK",
        "description": "Civil records background check description..."
      }
      {
        "id": "YOUR-PKG-ID-0004",
        "name": "SSN Verification",
        "type": "BACKGROUND_CHECK",
        "description": "SSN verification background check description..."
      }
    ]
  }'
Your customer will then be able to view your submitted packages in their ATS:

What the UI for triggering a new assessment looks like in Greenhouse.

​
2. Reacting to new assessment or background check orders

Please refer to this guide for reacting to new inline assessment orders.
Your customer triggers an assessment or background check for a specific candidate from their ATS. Kombo will then notify you that a new assessment or background check order has been created.
  • For assessments, you should then send out an email to the candidate to take the test on your platform. The candidate will then complete your assessment.
  • For background checks, you could send out an email to the candidate to fill in additional information required by the background check that are not stored on the ATS.
assessment:order-received
{
  "id": "B5KQKhAgTv6ZwzrfAbqbhipd",
  "integration_id": "workday:CBNMt7dSNCzBdnRTx87dev4E",
  "package_id": "typescript_test",
  "status": "OPEN",
  "candidate": {
    "email": "john.doe@gmail.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1 123 456 7890",
    "remote_id": "26vafvWSRmbhNcxJYqjCzuJg"
  },
  "application": {
    "remote_id": "HAQ9uCfC1zi3TLbB1n5cyHgP"
  },
  "job": {
    "remote_id": "A1KQKhAgTv6ZwzrfAbqbhcde",
    "name": "Engineering Manager",
    "location": {
      "city": "Berlin",
      "country": "DE",
      "raw": "Berlin, Germany",
      "state": "Berlin",
      "street_1": "Lohmühlenstraße 65",
      "street_2": null,
      "zip_code": "12435"
    },
    "hiring_team": [
      {
        "first_name": "Jane",
        "last_name": "Doe",
        "remote_id": "26vafvWSRmbhNcxJYqjCzuJr",
        "email": "jane.doe@gmail.com",
        "hiring_team_roles": [
          "RECRUITER"
        ]
      }
    ]
  }
}
remote_data will contain the exact payload received from the customer’s webhook.
You can reject your customer’s order of a package by responding with 422 status code and body in the following shape: 
HTTP/1.1 422 Unprocessable Content
Date: Fri, 28 Jun 2024 12:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 187

{
  "status": "ORDER_REJECTED",
  "message": "There is an existing order for this candidate..."
}
We will then also display the message in the UI of the ATS so that your user knows what’s going on.
The response to the assessment:order-received webhook’s body needs to match the shape described in the example to make us to reject the assessment order!Other errors will not cause us to reject the assessment. We will still accept it and make it available via the Get open orders endpoint so that you can retry at a later point.

​
3. Writing back results

Once the candidate has completed your assessment, you send the results of the assessment or the background check to Kombo: 
curl --location --request PUT 'https://api.kombo.dev/v1/assessment/orders/B5KQKhAgTv6ZwzrfAbqbhipd/result' \
  --header 'X-Integration-Id: smartrecruiters:example_integration_id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer example_kombo_token' \
  --data '{
    "status": "COMPLETE",
    "score": 90,
    "max_score": 100,
    "result_url": "https://example.com",
    "completed_at": "2023-04-04T00:00:00.000Z",
    "attributes": [
      {
        "type": "TEXT",
        "label": "Role fit",
        "value": "Excellent"
      },
      {
        "type": "SUB_RESULT",
        "id": "<YOUR_INTERNAL_ID_OF_THE_TEST>",
        "label": "Personality test",
        "score": {
          "value": 97,
          "max": 100
        },
        "status": "COMPLETED"
      }
    ]
  }'
Kombo will write the assessment or background check results back into your customer’s ATS system. Your customer can then view the results directly in their ATS.

What assessment results look like within Greenhouse.