> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn how to get started with Kombo's unified ATS Assessment & Background Check API.

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. Submit your available packages via the [Set packages endpoint](/assessment/v1/put-packages) to Kombo. We'll take care of displaying them in your customers' ATSs. Your customers can then choose the packages and create assessment or background check orders from their ATSs.
2. When your customer triggers a new assessment or background check order in the ATS, Kombo sends you an `assessment:order-received` [webhook event](/assessment/webhooks/assessment-order-received), so you can automatically send out an email to the candidate and get the assessment or the background check process started on your side.
3. Once the candidate has completed their assessment or the background check status has been updated, you can write back the results to the ATSs with the [Update order result endpoint](/assessment/v1/put-orders-assessment-order-id-result) via Kombo. Your customers will be able to view the results directly within their ATSs.

Continue reading to learn more about what these steps look like in practice.

## Setup: Connecting a new customer

<Frame caption="Kombo Connect guides your customer through the process of connecting their ATS.">
  <img width="500" src="https://mintcdn.com/kombo/OkxC1UMu0PfEDAZt/images/assessments-connection-flow.png?fit=max&auto=format&n=OkxC1UMu0PfEDAZt&q=85&s=719ac2febb06e3cfb12c01e1d48cc630" data-path="images/assessments-connection-flow.png" />
</Frame>

Use [Kombo Connect](/assessment/guides/connect/introduction) to set up your integrations with your customers. We'll guide your customers through the process of setting up their integrations.

## Implementation Overview

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Kombo
    participant ATS

    Note over You, ATS: Configure Packages
    You->>Kombo: Set assessment test packages<br/>PUT `/assessment/packages`
    Kombo<<-->>ATS: List packages

    Note over You, ATS: Order Assessment or Background Check
    ATS-->>Kombo: New assessment or background check<br/>order event
    Kombo-->>Kombo: Process order
    Kombo->>You: Receive new order<br/>`assessment:order-received` event

    Note over You, ATS: Update Result
    You->>You: Perform assessment/background check
    You->>You: Generate report and score
    You->>Kombo: Update order result<br/>PUT `/assessment/orders/{order_id}/result`
    Kombo-->>ATS: Write result to ATS
```

<Tip>
  Check out how to use Kombo's [Sandbox Integration](/assessment/features/assessment-ui#development-flow) to speed up your implementation.
</Tip>

<Steps>
  <Step title="Configure Available Packages" titleSize="h3">
    [Submit](/assessment/v1/put-packages) all your available assessment and/or background check packages for the customer once they have connected via Kombo. Kombo automatically configures the ATS to surface the packages to your customer.

    ```shell theme={null}
    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": "Coding Test",
            "description": "Coding test description...",
            "type": "SKILLS_TEST"
          },
          {
            "id": "YOUR-PKG-ID-0002",
            "name": "Psychometric Test",
            "description": "Psychometric test description...",
            "type": "SKILLS_TEST"
          },
          {
            "id": "YOUR-PKG-ID-0003",
            "name": "Visa Status",
            "description": "Visa status check...",
            "type": "BACKGROUND_CHECK"
          },
          {
            "id": "YOUR-PKG-ID-0004",
            "name": "SSN Verification",
            "description": "SSN verification check...",
            "type": "BACKGROUND_CHECK"
          }
        ]
      }'
    ```

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

    <Frame caption="What the UI for triggering a new assessment looks like in Greenhouse.">
      <img width="400" src="https://mintcdn.com/kombo/XSs1WDsyPPBvaoxy/images/assessments-greenhouse-test.png?fit=max&auto=format&n=XSs1WDsyPPBvaoxy&q=85&s=9c0696e574a26e64bdfde111bfee79b2" data-path="images/assessments-greenhouse-test.png" />
    </Frame>
  </Step>

  <Step title="Reacting to New Assessment or Background Check Orders" titleSize="h3">
    <Note>
      For **Inline Assessment**, please refer to [this guide](/assessment/features/inline-assessment) for reacting to new inline assessment orders.
    </Note>

    When 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 via the `assessment:order-received` [webhook event](/assessment/webhooks/assessment-order-received).

    * 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 is not stored on the ATS.

    ```json assessment:order-received theme={null}
    {
      "id": "Cbfk5sHtDxrSrJBRjsDtbaN9",
      "type": "assessment:order-received",
      "data": {
        "id": "B5KQKhAgTv6ZwzrfAbqbhipd",
        "integration_id": "workday:CBNMt7dSNCzBdnRTx87dev4E",
        "package_id": "typescript_test",
        "status": "OPEN",
        "candidate": {
          "remote_id": "12345",
          "email": "john.doe@gmail.com",
          "first_name": "John",
          "last_name": "Doe",
          "phone": "+1 123 456 7890"
        },
        "application": {
          "remote_id": "54321"
        },
        "job": {
          "remote_id": "67890",
          "name": "Bottle Opener",
          "job_code": "BO-2024-01",
          "description": "<p>We are looking for a skilled and energetic individual to join our team as the chief bottle open officer. This unique role requires precision, attention to detail, and the ability to handle a high volume of beverage bottles in a fast-paced environment. The ideal candidate will ensure bottles are opened swiftly and safely while maintaining hygiene standards.</p>",
          "location": {
            "street_1": "Lohmühlenstraße 65",
            "city": "Berlin",
            "state": "Berlin",
            "zip_code": "12435",
            "country": "DE",
            "raw": "Berlin, Germany"
          },
          "hiring_team": [
            {
              "first_name": "Jane",
              "last_name": "Doe",
              "remote_id": "78901",
              "email": "jane.doe@gmail.com",
              "hiring_team_roles": [
                "RECRUITER"
              ]
            }
          ]
        }
      }
    }
    ```

    <Tip>Please refer to [this guide](/assessment/guides/webhooks#validate-the-data) on how to validate Kombo's webhooks.</Tip>

    You can reject your customer’s order of a package by responding with a `422` status code and body in the following shape:

    ```http theme={null}
    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..."
    }
    ```

    <Info>
      We will propagate the error message from the `message` field back to the ATS's UI if it is supported by their API, so that your customers can understand what’s going on.
    </Info>

    <Warning>
      The response to the `assessment:order-received` webhook’s body needs to match the shape described in the example to make us 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](/assessment/v1/get-orders-open) endpoint so that you can retry at a later point.
    </Warning>
  </Step>

  <Step title="Write Back Results" titleSize="h3">
    Once the candidate has completed your assessment or the background check has been updated for the candidate, you can [update the results](/assessment/v1/put-orders-assessment-order-id-result) of the assessment or the background check via Kombo:

    ```shell theme={null}
    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": "COMPLETED",
        "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"
          },
          {
            "type": "TEXT",
            "label": "SSN Status",
            "value": "Valid"
          }
        ],
        "attachments": [
          {
            "name": "Assessment Report.pdf",
            "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
            "content_type": "application/pdf"
          }
        ]
      }'
    ```

    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.

    <Frame caption="What an overview of a candidate's result looks like within Greenhouse.">
      <img width="500" src="https://mintcdn.com/kombo/XSs1WDsyPPBvaoxy/images/assessments-greenhouse-result-overview.png?fit=max&auto=format&n=XSs1WDsyPPBvaoxy&q=85&s=800ee6aadc8e212c6621b5c0b833c34a" data-path="images/assessments-greenhouse-result-overview.png" />
    </Frame>

    <Frame caption="What a detailed result looks like within Greenhouse.">
      <img width="350" src="https://mintcdn.com/kombo/XSs1WDsyPPBvaoxy/images/assessments-greenhouse-detailed-result.png?fit=max&auto=format&n=XSs1WDsyPPBvaoxy&q=85&s=d1902724d3ab771a4471bd2906af65e9" data-path="images/assessments-greenhouse-detailed-result.png" />
    </Frame>
  </Step>
</Steps>
