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