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.

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

{
  "type": "screening",
  "payload": {
    "id": "839472998",
    "packageId": "96193",
    "candidate": {
      "email": "john.doe@example.com",
      "givenName": "John",
      "familyName": "Doe",
      "confirmedNoMiddleName":false,
      "dob":"1972-09-21",
      "ssn":"123456789",
      "phone":"17021234567",
      "address":{
        "addressLine":"123 Sterling St.",
        "municipality":"BOTHELL",
        "regionCode":"WA",
        "postalCode":"98011",
        "countryCode":"USA",
        "validFrom":"0001-01-01T00:00:00",
        "validTo":"0001-01-01T00:00:00"
      },
      "screeningIds":[],
      "driversLicense":{
        "type":"personal",
        "licenseNumber":"S1234567",
        "issuingAgency":""
      }
    },
    "candidateId":"faa75203-4c67-48da-b3b9-fbdd6b0c31ea",
    "status":"Complete",
    "result":"Clear",
    "links":{
      "admin":{
        "web":"https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=mwqMxus31%2fMcSKPxq6ZH4Q%3d%3d&BGORDERID=pMSMq00Kntb%2f0AM4ggigFkemex0roy%2fgXrfCXd77LLU%3d"
      }
    },
    "reportItems":[
      {
        "id":"11828946",
        "type":"SSN Trace",
        "status":"Complete",
        "result":"Complete",
        "updatedAt":"2018-11-15T17:32:00"
      },
      {
        "id":"11828947",
        "type":"Locator Select",
        "status":"Complete",
        "result":"Clear",
        "updatedAt":"2018-11-18T18:32:00"
      },
      {
        "id":"11828948",
        "type":"DOJ Sex Offender Search",
        "status":"Complete",
        "result":"Clear",
        "updatedAt":"2018-11-15T17:33:00"
      }
    ],
    "submittedAt":"2018-11-15T17:32:18",
    "updatedAt":"2018-11-15T17:33:00"
  }
}

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


`PreDraft`	Email sent; Information from candidate is required
`Draft`	Client information gathered; Ready to begin processing
`Pending`	Processing; At least 1 report item within this package has a status of pending
`Cancelled`	The candidate did not submit their data by the expiration date
`Complete`	All report items are set to complete within the package

Report Results

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


`Clear`	Everything good, the screening passes.
`Consider`	Something found. The screening needs review.

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