RefappRefapp

ATS partner 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.

#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 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. From then on your system serves every customer you share with Refapp. What changes lists the differences.

The pages below describe the dedicated endpoint:

  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.
  4. 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.

PurposeEndpoint
Project configurationGET https://<refapp host>/webhooks/<your-ats-name>/config (or POST, see Configuration)
Candidate creationPOST 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 integrationDedicated endpoint
Path/webhooks/account-integration/webhooks/<your-ats-name>
Bearer tokenA token of the account. It also says which account you act for.Your partner credential, the same for every customer.
Which accountGiven by the token.The customer secret: the X-Provider-Key header on configuration, company.uuid in the body on submit.
company in the submit bodyIgnored.Required.
Where status updates goA 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 authenticateChosen by the account administrator in Refapp.Agreed with your partnership contact, per host.
Reading statusPush, or pull with GET /api/v1/account/…/results.Push only. There is no endpoint to read the status from.
Connecting a customerAn 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.