As an assessment provider, you want to reduce the friction for your customers to order assessments for their candidates.

By building on top of Kombo’s Unified ATS-Assessment API, you can allow your customers to seamlessly start assessments right from their Applicant Tracking System (ATS).

Here’s how it works:

  1. You submit your available assessment packages to Kombo. We’ll take care of configuring them in your customer’s integration. Your customers can now submit assessment orders from their ATS.
  2. When your customer triggers a new assessment order in the ATS, Kombo sends you a webhook event, so you can automatically send out an email and get the assessment process started.
  3. Once the candidate has completed the assessment, you send the results to Kombo. We then write them to the ATS system.
  4. Your customers can conveniently access the assessment 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 packages for the customer to Kombo. Kombo automatically configures the ATS to surface the assessment 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",
        "description": "Postgres test description..."
      },
      {
        "id": "YOUR-PKG-ID-0002",
        "name": "Javascript",
        "description": "Javascript test description..."
      }
    ]
  }'

Your customer will then be able to view your submitted tests in their ATS:

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

​
2. Reacting to new assessment orders

Your customer triggers an assessment for a specific candidate from their ATS. Kombo will then notify you that a new assessment order has been created.

assessment:order-received
{
  "id": "HAQ9uCfC1zi3TLbB1n5cyHgP",
  "type": "assessment:order-received",
  "data": {
    "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
    "package_id": "typescript_test",
    "status": "OPEN",
    "integration_id": "workday:CBNMt7dSNCzBdnRTx87dev4E",
    "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": "Internal Manager",
      "location": {
        "city": "Wien",
        "country": "AT",
        "raw": "123 Alexander street",
        "state": "Wien",
        "street_1": null,
        "street_2": null,
        "zip_code": "1060"
      },
      "hiring_team": [
        {
          "email": "john.kase@hire.it",
          "first_name": "John",
          "last_name": "Kase",
          "remote_id": "63906e1k9180452d6e91b8bf"
          "hiring_team_roles": ["RECRUITER"]
        }
      ]
    },
    "remote_data": {
      "upstream_webhook_body": {
        ...
      },
      "/additionally-fetched-data": {
        ...
      }
    }
  }
}

remote_data will contain the exact payload received from the customer’s webhook.

You should then send out your assessment (through an email, for example) to the candidate to be assessed. The candidate will then complete your assessment.

​
3. Writing back results

Once the candidate has completed your assessment, you send the results of the assessment 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 '{
    "result_url": "https://example.com",
    "attributes": [
      {
        "key": "Time taken (minutes)",
        "value": "45"
      },
      {
        "key": "Role fit",
        "value": "HIGH"
      }
    ],
    "status": "COMPLETE",
    "score": 81,
    "completed_at": "2023-04-04T00:00:00.000Z"
  }'

Kombo will write the assessment results back into your customer’s ATS system. Your customer can then view the assessment results directly in their ATS.

What assessment results look like within Greenhouse.

Overview