# Submit a candidate

`POST https://{host}/webhooks/ats-generic`

Creates the candidate, and the project for `candidate.job.id` if it does not exist yet, on the account named by `company.uuid`. Idempotent: the same request again takes no new action. Answers 201 as soon as the request is received, whatever happened next; read `data` or `errorMessage` in the body to know.

## Authentication

`Authorization: Bearer <token>`

The partner credential Refapp issued to your ATS. It identifies the vendor; the customer comes from `X-Provider-Key` or `company.uuid`.

## Body

application/json, required

- `partner-event`, object, required
  - `id`, string
  - `company`, object, required
    - `name`, string | null
    - `uuid`, string, required
    - `ats-url`, string | null
  - `candidate`, object, required
    - `id`, number | string, required
    - `first-name`, string | null
    - `last-name`, string | null
    - `email`, string | null
    - `phone`, string | null
    - `country-calling-code`, string | null
    - `referees`, array of object | null
      - `first-name`, string | null
      - `last-name`, string | null
      - `email`, string | null
      - `phone`, string | null
      - `country-calling-code`, string | null
      - `language`, string | null
    - `employment-history`, array of object | null
      - `organisation`, string, required: `minLength: 1`
      - `position`, string | null: `minLength: 1`
      - `start`, string, required: `pattern: ^\d{4}-(0[1-9]|1[0-2])$`
      - `end`, string | null: `pattern: ^\d{4}-(0[1-9]|1[0-2])$`
      - `is-current`, boolean | null
    - `recruiter`, object, required
      - `name`, string | null
      - `first-name`, string | null
      - `last-name`, string | null
      - `email`, string, required
      - `phone`, string | null
      - `country-calling-code`, string | null
      - `ats-url`, string | null
      - `external-user-identifier`, string | array of string | null
        - `Alternative 1`, string
        - `Alternative 2`, array of string
    - `job`, object, required
      - `id`, number | string, required
      - `alternate-ids`, array of number | string | null
      - `title`, string, required
      - `private-title`, boolean | null
      - `client-name`, string | null
      - `recruiting-team`, array of object | null
        - `name`, string | null
        - `first-name`, string | null
        - `last-name`, string | null
        - `email`, string, required
        - `phone`, string | null
        - `country-calling-code`, string | null
        - `ats-url`, string | null
        - `external-user-identifier`, string | array of string | null
          - `Alternative 1`, string
          - `Alternative 2`, array of string
      - `ats-url`, string | null
      - `ats-public-key`, string | null
      - `ats-name`, string | null
      - `description`, string | null
    - `language`, string | null
    - `ats-url`, string | null
  - `partner-result`, object, required
    - `id`, string, required
    - `status`, string: One of `"sending"`, `"sent"`, `"pending"`, `"completed"`, `"failed"`
    - `update-url`, string | null
  - `webhook-data`, object | null
    - `(any other key)`, string | boolean | number

### Example body

```json
{
  "partner-event": {
    "id": "string",
    "company": {
      "name": "string",
      "uuid": "string",
      "ats-url": "string"
    },
    "candidate": {
      "id": 0,
      "first-name": "string",
      "last-name": "string",
      "email": "string",
      "phone": "string",
      "country-calling-code": "string",
      "referees": [
        {
          "first-name": "string",
          "last-name": "string",
          "email": "string",
          "phone": "string",
          "country-calling-code": "string",
          "language": "string"
        }
      ],
      "employment-history": [
        {
          "organisation": "string",
          "position": "string",
          "start": "string",
          "end": "string",
          "is-current": true
        }
      ],
      "recruiter": {
        "name": "string",
        "first-name": "string",
        "last-name": "string",
        "email": "string",
        "phone": "string",
        "country-calling-code": "string",
        "ats-url": "string",
        "external-user-identifier": "string"
      },
      "job": {
        "id": 0,
        "alternate-ids": [
          0
        ],
        "title": "string",
        "private-title": true,
        "client-name": "string",
        "recruiting-team": [
          {
            "name": "string",
            "first-name": "string",
            "last-name": "string",
            "email": "string",
            "phone": "string",
            "country-calling-code": "string",
            "ats-url": "string",
            "external-user-identifier": "string"
          }
        ],
        "ats-url": "string",
        "ats-public-key": "string",
        "ats-name": "string",
        "description": "string"
      },
      "language": "string",
      "ats-url": "string"
    },
    "partner-result": {
      "id": "string",
      "status": "sending",
      "update-url": "string"
    },
    "webhook-data": {}
  }
}
```

## Responses

### 201 (application/json)

Received. `data` is present when the candidate was created or found, `errorMessage` when Refapp could not act on the request.

- `message`, string, required
- `data`, object
  - `type`, string, required: Always `"partner-results"`
  - `id`, string, required
  - `attributes`, object, required
    - `status`, string, required: One of `"sending"`, `"sent"`, `"pending"`, `"completed"`, `"failed"`
    - `summary`, string, required
    - `url`, string
    - `candidateLink`, object
      - `url`, string, required
      - `description`, string, required
      - `type`, string: One of `"report-url"`, `"report-pdf-data"`, `"candidate-url"`
    - `candidateSubmissionPageLink`, object
      - `url`, string, required
      - `description`, string, required
      - `type`, string: One of `"report-url"`, `"report-pdf-data"`, `"candidate-url"`
    - `assessment`, object
      - `type`, string: Always `"reference-check"`
      - `score`, number
      - `total`, number
      - `remainingToSubmit`, number
      - `completed`, number
      - `declined`, number
      - `fraudWarnings`, array of string
    - `attachments`, array of object
      - `url`, string, required
      - `description`, string, required
      - `type`, string: One of `"report-url"`, `"report-pdf-data"`, `"candidate-url"`
    - `criteria`, object: Values to route the candidate on, keyed by criterion id. `moving_criteria` in `GET /webhooks/ats-generic/config` is the source of truth for the criteria and values that this account receives. This reference shows only the criteria and values that exist today. A criterion is left out until it has a value. Criteria and values can be added or removed at any time. Refapp avoids breaking changes, so a new criterion or value is more likely than a removed one or a changed value type. Ignore ids and values that you do not know.
      - `background_check_outcome`, string: Where the background check stands. `anomalies_*` once it found anomalies: pending until a reviewer approves or rejects them. `declined` when the candidate declined. More values can be added.. One of `"in_progress"`, `"clear"`, `"anomalies_pending_review"`, `"anomalies_approved"`, `"anomalies_rejected"`, `"declined"`
      - `reference_check_fraud`, string: `warning` while a fraud warning is active on the candidate. More values can be added.. One of `"positive"`, `"warning"`
      - `reference_check_referees_overdue`, string: `overdue` once the deadline for adding referees has passed and the candidate has not added all requested referees. More values can be added.. One of `"overdue"`, `"not_overdue"`
      - `reference_check_behaviours`, string: `warning` when a behavioural trait fell outside the target range, `insufficient` when too few referees answered to compare against the benchmark. More values can be added.. One of `"positive"`, `"warning"`, `"insufficient"`
      - `reference_check_cwb`, string: `warning` when a referee reported a counterproductive work behaviour. More values can be added.. One of `"positive"`, `"warning"`
      - `reference_check_recommendation`, number: How strongly the referees recommend the candidate, in percent.. `minimum: 0`. `maximum: 100`
      - `(any other key)`, string | number
    - `details`, object: Text in the account's language to show to a recruiter. The keys are names and labels, which can change. Routing rules must use `criteria`, not `details`.
      - `(any other key)`, string | object
        - `Alternative 1`, string
        - `Alternative 2`, object
          - `(any other key)`, string
- `errorMessage`, string
- `localizableErrorMessage`, string
- `info`, object

### 401 (text/plain)

The token is missing, unknown, revoked, or the integration is not enabled for the account. All four look the same.
