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:

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.

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:

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

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.