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

```json
{
  "partner-event": {
    "company": {
      "uuid": "yyy-customer-secret-yyy"
    },
    "candidate": {
      "id": "www",
      "first-name": "Alex",
      "last-name": "Lindqvist",
      "email": "alex.lindqvist@example.com",
      "phone": "+46701234567",
      "language": "sv",
      "job": {
        "id": "zzz",
        "title": "Full-stack web developer"
      },
      "recruiter": {
        "first-name": "Sam",
        "last-name": "Berg",
        "email": "sam.berg@yourcompany.example",
        "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](generic-ats-status-updates).                                                                                               |
| `webhook-data`              | The recruiter's choices from the [configuration](generic-ats-configuration) form, keyed by field `id`. Which keys appear depends on the customer's settings.    |

Every field is described in the [API reference](/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`:

```json
{
  "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": "sam.berg@yourcompany.example",
            "phone": "+46701234568"
          }
        ]
      },
      "recruiter": {
        "email": "sam.berg@yourcompany.example"
      }
    },
    "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.

```json
{
  "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:

```json
{
  "message": "Handled Generic ATS for test partner data",
  "errorMessage": "invalid-email-domain",
  "localizableErrorMessage": "ATS_RECRUITER_EMAIL_DOMAIN_NOT_WHITELISTED",
  "info": {
    "companyId": "Aa1a1AaaA1Aa1Aa1a",
    "email": "sam.berg@yourcompany.example"
  }
}
```
