RefappRefapp

Generic ATS integration

View as Markdown

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:

  1. Configuration: fetch the settings a recruiter can choose for a reference check, and render them in your product.
  2. Reference check: send the candidate and the chosen settings to Refapp, which creates the candidate and starts the process.
  3. 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:

PurposeEndpoint
Project configurationGET https://test.refapp.se/webhooks/ats-generic/config (or POST, see Configuration)
Candidate creationPOST 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.