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.

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 is the
source of truth for the criteria and values that an account receives. The
API 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

curl -H "Authorization: Bearer 2YZtYcTMjqf8reK6Uyzhv3vh0mwyIRWy" \
     -H "Content-Type: application/json" \
     -X PUT "https://app.partnersystem.example/reference-status" \
     -d @body.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.

{
  "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.

{
  "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"
    }
  }
}