Reference check

Send the candidate to Refapp to start the reference check. Refapp creates the
candidate, and the project for the position if it does not exist yet, and
depending on the chosen settings starts asking the candidate for referees by
email or SMS.

Request

POST https://test.refapp.se/webhooks/ats-generic
Authorization: Bearer <partner credential>
Content-Type: application/json

Only the Authorization header is needed. The customer is named inside the
body, in company.uuid.

The endpoint behaves like a webhook receiver:

It is idempotent. The same request received twice takes no new action,
because the candidate already exists.
It always answers 201 once the request has been received, whatever
Refapp could do with it. To know whether it succeeded, look at the body: a
data object with type equal to partner-results means the candidate was
created or found; an errorMessage at the root means Refapp could not act.

{
  "partner-event": {
    "company": {
      "uuid": "yyy-customer-secret-yyy"
    },
    "candidate": {
      "id": "www",
      "first-name": "Alex",
      "last-name": "Lindqvist",
      "email": "[email protected]",
      "phone": "+46701234567",
      "language": "sv",
      "job": {
        "id": "zzz",
        "title": "Full-stack web developer"
      },
      "recruiter": {
        "first-name": "Sam",
        "last-name": "Berg",
        "email": "[email protected]",
        "phone": "+46701234568"
      }
    },
    "partner-result": {
      "id": "vvv",
      "update-url": "https://app.partnersystem.example/reference-status"
    },
    "webhook-data": {
      "hide-project-name": false,
      "external-recruitment": false,
      "external-recruitment-customer": "",
      "external-recruitment-hide-customer": false,
      "form-sv": "JsRBfndvYDWNxE6Qm",
      "form-en": "F9aMavknzygEwTosh",
      "relation-verification": true,
      "referee-requests-choice": "email-sms",
      "num-referees-requested": "2",
      "referee-communication-automation": "email-sms"
    }
  }
}

Member	Meaning
`partner-event`	Wraps everything.
`company.uuid`	The customer secret, the same value as the `X-Provider-Key` header in the configuration request. It selects the account.
`candidate.id`	Your unique id for this reference checking process. Use the candidate's id in your system, or one per application if a candidate can be checked more than once.
`candidate.job`	The position. `id` groups candidates into the same Refapp project; `title` names the project when Refapp creates it.
`candidate.recruiter`	The person handling the process. If the account allows it, Refapp provisions a user for them so communications can go out in their name.
`partner-result.id`	Your id for the process on your side. Every status update carries it back.
`partner-result.update-url`	Where Refapp pushes status updates.
`webhook-data`	The recruiter's choices from the configuration form, keyed by field `id`. Which keys appear depends on the customer's settings.

Every field is described in the API reference.

Letting the candidate submit referees through a link

For referee-requests-choice, your system may send the special value link.
Refapp then creates the referee submission request without sending any email
or SMS, as the "Copy web link" button does in Refapp, and returns the page's
URL in candidateSubmissionPageLink inside attributes. Show that link to
the candidate yourself.

Giving more people access

To let more users see the reference check in Refapp, add a recruiting-team
list to job. Each entry has the same shape as recruiter:

{
  "partner-event": {
    "company": { "uuid": "yyy-customer-secret-yyy" },
    "candidate": {
      "id": "www",
      "job": {
        "id": "zzz",
        "title": "Full-stack web developer",
        "recruiting-team": [
          {
            "first-name": "Sam",
            "last-name": "Berg",
            "email": "[email protected]",
            "phone": "+46701234568"
          }
        ]
      },
      "recruiter": {
        "email": "[email protected]"
      }
    },
    "partner-result": { "id": "vvv" }
  }
}

Responses

The candidate was created

The attributes object is the same status update Refapp will push to your
update-url, so you do not have to parse it here; accepting the push is
enough. Display texts come in the account's language, Swedish in this
example, so they can be shown to the recruiter as they are.

{
  "message": "Handled Generic ATS for test partner data",
  "data": {
    "type": "partner-results",
    "id": "vvv",
    "attributes": {
      "status": "pending",
      "summary": "Kandidatens referenser håller på att samlas in – 0 av 2 är klara",
      "attachments": [
        {
          "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
          "description": "Länk till kandidat i Refapp"
        }
      ],
      "candidateLink": {
        "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
        "description": "Länk till kandidat i Refapp"
      },
      "assessment": {
        "score": 0,
        "type": "reference-check",
        "total": 2,
        "remainingToSubmit": 2,
        "completed": 0,
        "fraudWarnings": []
      }
    }
  },
  "info": {
    "providerId": "yyy",
    "companyId": "Aa1a1AaaA1Aa1Aa1a",
    "added-new-users": "b2B2222BBBbbBBbBb",
    "added-project": "cCCcCcCcCcCccCcCC",
    "added-candidate": "DDDDDddddDddD9dD9"
  }
}

The info object is diagnostic and its contents may change; do not build on
it.

Refapp could not act

Here the recruiter's email domain is not allowed on the account:

{
  "message": "Handled Generic ATS for test partner data",
  "errorMessage": "invalid-email-domain",
  "localizableErrorMessage": "ATS_RECRUITER_EMAIL_DOMAIN_NOT_WHITELISTED",
  "info": {
    "companyId": "Aa1a1AaaA1Aa1Aa1a",
    "email": "[email protected]"
  }
}