# Status updates

Refapp pushes progress to your system as `PUT` requests to the `update-url`
you gave in `partner-result` when submitting the candidate. You receive one
when the candidate is created, one on every change of state, and one when all
referees have answered and the report is ready.

## What Refapp needs from you

Before the first push, agree two things with your partnership contact:

| Item     | Example                            | Purpose                                                                                                                                  |
| -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname | `app.partnersystem.example`        | Every `update-url` is checked against an allow-list of your hostnames, so a mistaken URL can never send candidate data to a third party. |
| Token    | `2YZtYcTMjqf8reK6Uyzhv3vh0mwyIRWy` | Sent as `Authorization: Bearer <token>` on every push, so your endpoint can verify the sender.                                           |

Answer any push with a 2xx status. Anything else is treated as a failed
delivery on Refapp's side.

## The body

The body is the same `partner-results` object returned when the candidate was
submitted. `status` is one of `sending`, `sent`, `pending`, `completed` or
`failed`. `summary` is a line in the account's language that you can show to
the recruiter directly. `assessment` holds the counts behind the summary, and
`attachments` the links worth showing: the candidate in Refapp and, once
available, the report. The full shape is in the [API reference](/reference).

`criteria` holds the values of the routing criteria, keyed by criterion `id`.
A criterion is left out until it has a value. `details` shows the same values
as text in the account's language, keyed by criterion name, for a recruiter to
read. Names and labels can change. For this reason, routing rules must use
`criteria`, not `details`.

`moving_criteria` in the [config endpoint](generic-ats-configuration) is the
source of truth for the criteria and values that an account receives. The
[API reference](/reference) shows only the criteria and values that exist
today. 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 an `id` or a value that you do not know.

## Examples

### First push, right after the candidate was created

```shell
curl -H "Authorization: Bearer 2YZtYcTMjqf8reK6Uyzhv3vh0mwyIRWy" \
     -H "Content-Type: application/json" \
     -X PUT "https://app.partnersystem.example/reference-status" \
     -d @body.json
```

```json
{
  "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,
      "completed": 0,
      "fraudWarnings": []
    }
  }
}
```

### In progress, with a fraud warning

One of three referees has answered, from the same IP address as the
candidate. The warning appears both in `summary` and as a code in
`fraudWarnings`.

```json
{
  "type": "partner-results",
  "id": "vvv",
  "attributes": {
    "status": "pending",
    "summary": "Kandidatens referenser håller på att samlas in – 1 av 3 är klara\n\nMisstänkt bedrägeri",
    "url": "https://test.refapp.se/report/DDDDDddddDddD9dD9",
    "attachments": [
      {
        "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
        "description": "Länk till kandidat i Refapp"
      },
      {
        "url": "https://test.refapp.se/report/DDDDDddddDddD9dD9",
        "description": "Refapp referensrapport"
      }
    ],
    "candidateLink": {
      "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
      "description": "Länk till kandidat i Refapp"
    },
    "assessment": {
      "score": 33.33333333333333,
      "type": "reference-check",
      "total": 3,
      "completed": 1,
      "fraudWarnings": ["same-ip-address"]
    }
  }
}
```

### Completed

All referees have answered and the report is ready at `url`.

```json
{
  "type": "partner-results",
  "id": "vvv",
  "attributes": {
    "status": "completed",
    "summary": "Kandidatens referenser har svarat i Refapp",
    "url": "https://test.refapp.se/report/DDDDDddddDddD9dD9",
    "attachments": [
      {
        "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
        "description": "Länk till kandidat i Refapp"
      },
      {
        "url": "https://test.refapp.se/report/DDDDDddddDddD9dD9",
        "description": "Refapp referensrapport"
      }
    ],
    "candidateLink": {
      "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
      "description": "Länk till kandidat i Refapp"
    },
    "assessment": {
      "score": 100,
      "type": "reference-check",
      "total": 2,
      "completed": 2,
      "fraudWarnings": []
    },
    "criteria": {
      "reference_check_fraud": "positive",
      "reference_check_referees_overdue": "not_overdue"
    },
    "details": {
      "Bedrägeri": "✅ Inget misstänkt",
      "Tidsfrist för referenser": "✅ Inte försenad"
    }
  }
}
```
