# ATS partner integration

This guide is for vendors of applicant tracking systems and HR platforms who
want to offer Refapp reference checking to their customers. One partner
credential authenticates your system. Each customer account in Refapp is
addressed by its own secret, so a single integration serves every shared
customer.

## Two phases

You build the integration in two phases. The payloads are the same in both, so
what you build in the first phase carries over to the second.

1. **Build against the account integration.** Refapp sets up an account for
   you in the test environment, `test.refapp.se`, with the
   [account integration](account-integration) enabled. From there you work on
   your own: you create your token in the account, send candidates, read the
   settings and receive results, without waiting for Refapp.
2. **Move to your dedicated endpoint.** When you are happy with your
   integration, ask your Refapp partnership contact for your endpoint. Refapp
   builds it and enables it in the test environment first, so you can make the
   move there before you [go live](#going-live). From then on your system
   serves every customer you share with Refapp.
   [What changes](#what-changes-when-you-move-to-your-dedicated-endpoint) lists
   the differences.

The pages below describe the dedicated endpoint:

1. [Configuration](ats-partner-configuration): fetch the settings a recruiter
   can choose for a reference check, and render them in your product.
2. [Reference check](ats-partner-reference-check): send the candidate and the
   chosen settings to Refapp, which creates the candidate and starts the
   process.
3. [Status updates](ats-partner-status-updates): receive progress and the
   finished report as pushes to your endpoint.
4. [Connecting a customer account](ats-partner-connect-account): let a
   customer link their Refapp account to your system without copying the
   secret by hand.

## Your endpoint

Refapp gives your ATS a name, and that name is part of the path of your
endpoint. This guide writes it as `<your-ats-name>`. Replace it with the name
you received, in the same spelling.

| Purpose               | Endpoint                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Project configuration | `GET https://<refapp host>/webhooks/<your-ats-name>/config` (or `POST`, see [Configuration](ats-partner-configuration)) |
| Candidate creation    | `POST https://<refapp host>/webhooks/<your-ats-name>`                                                                   |

Your endpoint is enabled on `test.refapp.se` first, so that is `<refapp host>`
until you go live. For the test environment your Refapp partnership contact
provides:

- The name of your ATS.
- The partner credential, sent as a bearer token on every request.
- One or more customer accounts in the test environment with your integration
  enabled, and the customer secret for each.

Every request and response is described in the
[ATS partner API reference](/reference/ats-partner). You can call the endpoints
from the browser there, with your ATS name and the host filled in.

## What changes when you move to your dedicated endpoint

|                                 | Account integration                                             | Dedicated endpoint                                                                                               |
| ------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Path                            | `/webhooks/account-integration`                                 | `/webhooks/<your-ats-name>`                                                                                      |
| Bearer token                    | A token of the account. It also says which account you act for. | Your partner credential, the same for every customer.                                                            |
| Which account                   | Given by the token.                                             | The customer secret: the `X-Provider-Key` header on configuration, `company.uuid` in the body on submit.         |
| `company` in the submit body    | Ignored.                                                        | Required.                                                                                                        |
| Where status updates go         | A URL pattern that the account administrator sets in Refapp.    | `partner-result.update-url` in each submit request, on a host that Refapp has registered for your ATS.           |
| How status updates authenticate | Chosen by the account administrator in Refapp.                  | Agreed with your partnership contact, per host.                                                                  |
| Reading status                  | Push, or pull with `GET /api/v1/account/…/results`.             | Push only. There is no endpoint to read the status from.                                                         |
| Connecting a customer           | An administrator creates a token in Refapp and gives it to you. | The customer follows a link from your product. See [Connecting a customer account](ats-partner-connect-account). |

Without a pull endpoint, your system must be able to receive
[status updates](ats-partner-status-updates) from the public internet.

## Integration flow

The flow on the dedicated endpoint:

```mermaid
sequenceDiagram
    participant R as Recruiter
    participant ATS as Your system
    participant Refapp
    participant C as Candidate

    R->>ATS: Opens reference check settings for a job
    ATS->>Refapp: GET /webhooks/your-ats-name/config
    Refapp-->>ATS: Form fields for this customer
    ATS-->>R: Renders the form
    R->>ATS: Chooses questionnaire, automation, referees
    R->>ATS: Starts a reference check for a candidate
    ATS->>Refapp: POST /webhooks/your-ats-name (candidate + webhook-data)
    Refapp-->>ATS: 201 with initial status
    Refapp->>C: Asks for referees (if automation is on)
    C-->>Refapp: Submits referees, referees answer
    Refapp->>ATS: PUT update-url (status pending, then completed)
    ATS-->>R: Shows progress and the report link
```

## Going live

When your integration works against your endpoint in the test environment,
Refapp enables the endpoint in production. To go live, you and Refapp exchange
what production needs:

- From Refapp: a new partner credential, and an account of your own on each
  production instance you use.
- From you: the hosts Refapp may send status updates to and return customers
  to, and the token Refapp sends with each status update.

Ask your partnership contact to start this step.

Use your production accounts for demos and for troubleshooting. Your account
in the test environment is for development and troubleshooting, not for demos.

No customer uses the integration before it is live. From then on, each
customer [connects their Refapp account](ats-partner-connect-account) to your
system.
