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.
- Build against the account integration. Refapp sets up an account for
you in the test environment,
test.refapp.se, with the 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. - 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. From then on your system serves every customer you share with Refapp. What changes lists the differences.
The pages below describe the dedicated endpoint:
- Configuration: fetch the settings a recruiter can choose for a reference check, and render them in your product.
- Reference check: send the candidate and the chosen settings to Refapp, which creates the candidate and starts the process.
- Status updates: receive progress and the finished report as pushes to your endpoint.
- Connecting a customer 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) |
| 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. 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. |
Without a pull endpoint, your system must be able to receive status updates from the public internet.
#Integration flow
The flow on the dedicated endpoint:
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 to your system.