Generic ATS 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.
The integration has three parts, each with its own page:
- 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 lets a customer link their Refapp account to your system without copying the secret by hand.
#Development environment
During development you work against the Refapp test environment as a generic partner account. Your Refapp partnership contact provides:
- The partner credential, sent as a bearer token on every request.
- One or more customer accounts in the test environment with the generic partner integration already enabled, and the customer secret for each.
Endpoints in the test environment:
| Purpose | Endpoint |
|---|---|
| Project configuration | GET https://test.refapp.se/webhooks/ats-generic/config (or POST, see Configuration) |
| Candidate creation | POST https://test.refapp.se/webhooks/ats-generic |
The older spelling /webhooks/genericAts still works for both.
Every request and response is described in the Generic ATS API reference, which you can call from the browser against the test environment.
#Integration flow
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/ats-generic/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/ats-generic (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
#Connecting a customer account
Customers can connect their Refapp account to your system themselves, by following a link from your product. See Connecting a customer account.
#Going live
When your integration has been validated in the test environment, Refapp enables it in production and exchanges production credentials with you: a new partner credential, the customer secrets of your shared customers, and the hostname and token Refapp should use for status updates. Ask your partnership contact to start this step.