RefappRefapp

Read a candidate's results

View as Markdown
GEThttps://{host}/api/v1/account/projects/{projectId}/candidates/{candidateId}/results

The same body the push sends. A reference check completes over days, so poll no more often than every five minutes.

Authentication

Authorization: Bearer <token>

The token Refapp issued for your account. It identifies the account, so nothing else is needed.

Path parameters

  • projectIdstringrequired

    The candidate.job.id you submitted.

  • candidateIdstringrequired

    The candidate.id you submitted.

Responses

200application/json

The candidate's current results.

Show response body
  • typestringrequired
    Always "partner-results"
  • idstringrequired
  • attributesobjectrequired
    Show properties
    • statusstringrequired
      One of "sending", "sent", "pending", "completed", "failed"
    • summarystringrequired
    • urlstring
    • candidateLinkobject
      Show properties
      • urlstringrequired
      • descriptionstringrequired
      • typestring
        One of "report-url", "report-pdf-data", "candidate-url"
    • candidateSubmissionPageLinkobject
      Show properties
      • urlstringrequired
      • descriptionstringrequired
      • typestring
        One of "report-url", "report-pdf-data", "candidate-url"
    • assessmentobject
      Show properties
      • typestring
        Always "reference-check"
      • scorenumber
      • totalnumber
      • remainingToSubmitnumber
      • completednumber
      • declinednumber
      • fraudWarningsarray of string
    • attachmentsarray of object
      Show item properties
      • urlstringrequired
      • descriptionstringrequired
      • typestring
        One of "report-url", "report-pdf-data", "candidate-url"
    • criteriaobject

      Values to route the candidate on, keyed by criterion id. moving_criteria in GET /webhooks/account-integration/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.

      Show properties
      • background_check_outcomestring

        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_fraudstring

        warning while a fraud warning is active on the candidate. More values can be added.

        One of "positive", "warning"
      • reference_check_referees_overduestring

        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_behavioursstring

        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_cwbstring

        warning when a referee reported a counterproductive work behaviour. More values can be added.

        One of "positive", "warning"
      • reference_check_recommendationnumber

        How strongly the referees recommend the candidate, in percent.

        minimum: 0 · maximum: 100
      • (any other key)string | number
    • detailsobject

      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.

      Show properties
      • (any other key)string | object
        Show alternatives
        • Alternative 1string
        • Alternative 2object
          Show properties
          • (any other key)string
Show example
{
  "type": "partner-results",
  "id": "string",
  "attributes": {
    "status": "sending",
    "summary": "string",
    "url": "string",
    "candidateLink": {
      "url": "string",
      "description": "string",
      "type": "report-url"
    },
    "candidateSubmissionPageLink": {
      "url": "string",
      "description": "string",
      "type": "report-url"
    },
    "assessment": {
      "type": "reference-check",
      "score": 0,
      "total": 0,
      "remainingToSubmit": 0,
      "completed": 0,
      "declined": 0,
      "fraudWarnings": [
        "same-ip-address"
      ]
    },
    "attachments": [
      {
        "url": "string",
        "description": "string",
        "type": "report-url"
      }
    ],
    "criteria": {
      "background_check_outcome": "in_progress",
      "reference_check_fraud": "positive",
      "reference_check_referees_overdue": "overdue",
      "reference_check_behaviours": "positive",
      "reference_check_cwb": "positive",
      "reference_check_recommendation": 0
    },
    "details": {}
  }
}
401application/json

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

Show response body
  • errorobjectrequired
    Show properties
    • codestringrequired
      One of "unauthorized", "not-found"
    • messagestringrequired
Show example
{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}
404application/json

No such project and candidate pair within your account. Another account's candidate answers the same way.

Show response body
  • errorobjectrequired
    Show properties
    • codestringrequired
      One of "unauthorized", "not-found"
    • messagestringrequired
Show example
{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}