RefappRefapp

Status updates

View as Markdown

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:

ItemExamplePurpose
Hostnameapp.partnersystem.exampleEvery update-url is checked against an allow-list of your hostnames, so a mistaken URL can never send candidate data to a third party.
Token2YZtYcTMjqf8reK6Uyzhv3vh0mwyIRWySent 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"
    }
  }
}