Callbacks

Background screenings involve gathering information from a variety of public and proprietary records, and as a result the response times for screenings can be unpredictable. As an API user, you can receive notifications when important events related to your screening occur. To receive update notifications, include a callback when creating a screening or subscription.

Callback Types

The callback type field supports future extensibility. At present, all callbacks are of the screening type.

Additional callback types may be introduced in the future. These new callback types will follow the same pattern as existing callbacks: the callback url will be specified in the POST request for the resource. This means that you are free to create one callback handling service exclusively for screenings and other services for each other callback type.

Alternatively, clients may implement a single general-purpose callback handler for all Sterling On Demand API callbacks. In that situation, the callback handler can use the type field to identify the message type and ensure that the intended parsing or business rules are applied only to the expected message types.

📘

Retries

Callbacks will retry every 15 minutes until an HTTP 200 success response is returned from your server. The retries will attempt 9 more times after the original (for a total of 10 attempts).

Screening Callbacks

The most common callback type will be a screening, as it is the object that will receive the most changes over time. A sample JSON payload for a screening callback can be seen below.

JSON

{
  "type": "screening",
  "payload": {
    "id": "001000063194810",
    "packageId": "101337",
    "candidateId": "8675309",
    "status": "complete",
    "result": "alert",
    "reportItems": [
      {
        "id": "62113371",
        "type": "Multi-State Instant Criminal Check",
        "status": "complete",
        "result": "no data",
        "updatedAt": "2016-07-08T21:42:46Z"
      },
      {
        "id": "62113372",
        "type": "Nationwide Sex Offender Registry Check",
        "status": "complete",
        "result": "alert",
        "updatedAt": "2016-07-08T21:42:46Z"
      }
    ],
    "submittedAt": "2017-04-26T20:41:27Z",
    "updatedAt": "2017-04-26T20:42:16Z",
    "dispute": {
      "status": "active",
      "createdAt": "2017-04-26T20:41:27Z"
    },
    "links": {
      "admin": {
        "web": "https://integration.talentwise.com/screening/report.php?ApplicantID=63194810",
        "pdf": "https://integration.talentwise.com/screening/pdf-report.php?ApplicantID=63194810"
      }
    },
    "adverseActions": [
      {
        "id": "001000063194810",
        "status": "awaiting-dispute",
        "updatedAt": "2017-04-26T20:41:27Z",
        "reportItemIds": [
          "62113372"
        ]
      }
    ]
  }
}

Callback Statuses

Every screening callback will have a status property in it's payload. The value of status will change depending on the status of each item in reportItems.

Package(Payload) Statuses

new	A new package was created
complete	All report items are set to complete within the package
pending	At least 1 report item within this package has a status of pending
release	A report item within this package is awaiting onset form
cancelled	Either the candidate did not submit their data by the expiration time or the API user account does not have the ability to create tickets.
n/a, error, other	Any other status should be treated as an error

Report Results

A report's result property will give a more detailed reason to why the report

clear	Everything good, the screening passes.
alert	Something found. The screening needs review.
client criteria	Check clientCriteriaResult which will have more information on whether or not the result meets a custom criteria

Report Statuses

Each individual report may have their own statuses and these will vary upon the type of report processed.

If using these statuses it's best practice to only concern yourself with the most common values. Here's a list of the top common Report Status values

Complete	The report has completed and result property is populated
Pending	The report started but is not completed yet.
Other	Any other status should be treated as an error
Expired	The report started but has expired due to inactivity.

📘

Callback Consumption

Callbacks from the Sterling API support data consumption in chunked and non-chunked variants. Chunking is possible when the callback payload data exceeds 1MB in size.