API
Sales

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.

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": "[email protected]",
      "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
PendingProcessing; At least 1 report item within this package has a status of pending
CancelledThe candidate did not submit their data by the expiration date
CompleteAll 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

ClearEverything good, the screening passes.
ConsiderSomething 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

CompleteThe report has completed and result property is populated
PendingThe report started but is not completed yet.
ExpiredThe 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.