{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"6bb7ca94-07a0-4e4d-9423-38f2f6b03a77","name":"Sterling API","description":"The Sterling API allows you to integrate background checks into your platform and manage the process from end-to-end.\n\nUsing the Sterling API, you can build applications that:\n\n- Initiate background checks on participants in an online marketplace.\n \n- Schedule recurring screenings to proactively monitor changes in a candidate's status over time.\n \n- Receive real-time updates for the screenings you initiate.\n \n\n# Getting Started\n\nAccess to the Sterling API can be provided by sending a request to our team using the following link: Request Credentials (Screening Region (**US**, **EMEA**, **Canada**, or **APAC**))\n\nOnce you receive your Client ID and Client Secret, here are the steps that API users typically follow to consume the Sterling APIs and perform end-to-end testing on your own.\n\n- Step 1: [POST Authentication](#27e4b4dc-590e-4fb2-b15e-6d4c606e4bdc)\n \n - Once you send an auth request with your Client ID and Client Secret, the response will contain an access token which can be used to send other requests to the API.\n \n- Step 2: [GET /packages](#64d38d48-79cf-4bd0-b279-678be6735489)\n \n - Retrieve a list of the packages available to you (a package is a group of screening products). The response will also specify which fields are required on a candidate record in order to process the associated screening.\n \n- Step 3: [POST /candidates](#14a4713e-423e-4c6f-a85b-6c24ca7d8147)\n \n - Create a candidate. Minimum fields for creation are first name, last name, email, and clientReferenceId. Further fields will likely be needed to initiate a screening on the candidate. The required fields can be identified via GET /packages.\n \n- Step 4: [POST /screenings](#3024bfa5-276c-4a45-90ea-c9e7df3e60f7)\n \n - You will need a candidateId and packageId in order to create a screening. You have 1-3 workflow options for creating a screening.\n \n - Send the candidate an email invite.\n \n - Receive a link to a form which you can either open within your app or on a new tab.\n \n - If all required candidate fields already exist, simply initiate the screening. Additionally, you can specify a Callback URI in this request which will allow you to receive real-time updates for the screenings you initiate.\n \n- Step 5: Process screenings using the [Developer Portal](#developer-portal)\n \n - Credentials to log into the Dev Portal are the same as your Client ID and Client Secret. The Dev Portal will allow you to manually set results for your screenings for end-to-end testing.\n \n- Step 6: Verify [callbacks](#callbacks)\n \n - In a POST /screenings request, you can set a Callback URI so that you can receive real-time updates for that screening.\n \n\n**Required Fields & Data Collection**\n\n> **Note:** You’ll want to consider the required candidate fields so that you can design your application to collect the pertinent information. \n \n> **Invite Feature:** If you don't want to collect all of the required candidate information then the alternative is to have Sterling handle the data collection. To use this feature, set the attribute `invite.method` to `\"email\"` to send the candidate an email, or set `invite.method` to `\"link\"` to receive the form URL within the API response when you call `POST /screenings`. \n \n\n**Going Live**\n\n> When testing is complete and you are ready to go live, be sure to switch your host endpoint to the production environment. This will also require you to obtain a **new** set of authentication credentials for that environment. Please reach out to your account manager when you are ready to start this process. \n \n\n# Authentication\n\n

Overview

\n\nThe Sterling API uses an OAuth2 (\"oauth\") authentication scheme. It supports the US, EMEA, Canada and APAC regions.\n\n**EMEA, Canada and APAC Support**\n\n> Currently, the EMEA, Canada and APAC regions are only supported in the Production environment. Any development testing required for a client expecting to go live in this region will need to test in the Integration environment using a US account. \n \n\n_**US**_\n\n| Environment | Endpoint |\n| --- | --- |\n| Integration | [https://api.us.int.sterlingcheck.app/v2/oauth](https://api.us.int.sterlingcheck.app/v2/oauth) |\n| Production | [https://api.us.sterlingcheck.app/v2/oauth](https://api.us.sterlingcheck.app/v2/oauth) |\n\n_**EMEA**_\n\n| Environment | Endpoint |\n| --- | --- |\n| Production | [https://api.eu.sterlingcheck.app/v2/oauth](https://api.eu.sterlingcheck.app/v2/oauth) |\n\n_**Canada**_\n\n| Environment | Endpoint |\n| --- | --- |\n| Production | [https://api.ca.sterlingcheck.app/v2/oauth](https://api.ca.sterlingcheck.app/v2/oauth) |\n\n_**APAC**_\n\n| Environment | Endpoint |\n| --- | --- |\n| Production | [https://api.au.sterlingcheck.app/v2/oauth](https://api.au.sterlingcheck.app/v2/oauth) |\n\n

Requests

\n\nRequests to the Sterling API must be authenticated using short-lived bearer token in the Authorization header. Applications will obtain bearer tokens via the oauth endpoint. It is also _required_ to set a \"grant_type\" field to \"client_credentials', as shown in the curl auth request example below.\n\n**cURL**\n\n```\ncurl -X POST \\\n-H \"Authorization: Basic \" \\\n-H 'Content-Type: application/x-www-form-urlencoded' \\\n-d 'grant_type=client_credentials' \\\nhttps://api.us.int.sterlingcheck.app/v2/oauth\n\n ```\n\nWhen making a request to the oauth endpoint, the basic auth credentials must be a base64 encoded string in the format `client_id:client_secret`. These credentials are not provided through the API and must be obtained through [First Advantage](https://www.sterlingcheck.com/industries/gig-economy/).\n\n**Base64**\n\n> The base64 encoded string for the credentials will remain unchanged unless your client_secret is changed at your request. \nFor instance, `example@example.com:86753O9` will always encode as `ZXhhbXBsZUBleGFtcGxlLmNvbTo4Njc1M085`. \n \n\nIf the provided credentials are valid, the oauth endpoint will provide a bearer token, along with an expiry time for the token (in seconds). An access_token will expire after 1 hour.\n\n**JSON Example**\n\n``` json\n{\n \"access_token\": \"RG8gcGVvcGxlIHJlYWxseSBkZWNvZGUgdGhlc2U/IEkgbWVhbiBzZXJpb3VzbHksIHRoaXMgaXMganVzdCBhIHRlc3QgaGFzaCEgV2VsbCwgaWYgeW91IG1hZGUgaXQgdGhpcyBmYXIsIGFsbG93IG1lIHRvIHJld2FyZCB5b3U6DQoNCmh0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1E=\",\n \"token_type\": \"bearer\",\n \"expires_in\": \"3600\"\n}\n\n ```\n\nThis token should be cached until it expires, and must be passed in the `Authorization` header of each request as follows:\n\n**cURL**\n\n```\ncurl -H \"Authorization: Bearer RG8gcGVvcGxlIHJlYWxseSBkZWNvZGUgdGhlc2U/IEkgbWVhbiBzZXJpb3VzbHksIHRoaXMgaXMganVzdCBhIHRlc3QgaGFzaCEgV2VsbCwgaWYgeW91IG1hZGUgaXQgdGhpcyBmYXIsIGFsbG93IG1lIHRvIHJld2FyZCB5b3U6DQoNCmh0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1E=\" \\\n-H \"Accept: application/json\" \\ \nhttps://api.us.int.sterlingcheck.app/v2/candidates/7212643\n\n ```\n\n**500 Errors**\n\n> If you receive a 500 error on any API call using an Authorization header, please check that the format is \"Bearer \\[base64\\]\". \n \n\n# Developer Portal\n\nSterling provides a [Developer Portal](https://developer.sterlingcheck.app/v2-login) to facilitate testing integrations and ensure all potential workflows are taken into account. Within the Dev Portal you can see all of your submitted screenings, as well as change their statuses.\n\n> The Dev Portal's functionality is specific to Sterling's **test environment**. You can log in with your client ID and secret once we have provisioned a test account and provided those credentials to you. \n \n\n\n\n# CMA (Client Matrix Application)\n\nDepending on your needs, you may be interested in a Client Matrix Application setup. This is not available by default and must be requested and configured prior to creating screenings. Depending on the criteria and the type of CMA configuration that is set up on your account, the API will be able to return a status that meets those expectations at a high-level. Please refer to our [Callbacks](#callbacks) section and the screening statuses for more information.\n\n

CMA Statuses

\n\nDepending on your account configuration, certain CMA statuses will be applicable to your integration. While working in our Developer Portal, you will notice a list of actions you can set on your screenings as displayed by the example below.\n\n\n\nAccounts set up with this configuration will either be set up for **2 or 3-score CMA**.\n\n_2-Score CMA_\n\n| Status | Description |\n| --- | --- |\n| `Passed` | Report has passed all criteria. |\n| `Review` | Discrepancies found on one or more of the report items; A manual score or initiating Adverse Action is advised. |\n\n_3-Score CMA_\n\nThe results listed below use customized criteria that is set by you in order to determine which level is returned. For example you may want all checks that have a series of discrepancies to return a `Level3`, whereas minor alerts could return a `Level1`.\n\nThis criteria can be determined and discussed with your account manager when gathering details for your account setup.\n\n| Attribute | Values |\n| --- | --- |\n| `result` | Level1, Level2, Level3 |\n\n# Callbacks\n\nBackground 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.\n\nIf you need to receive screening results summary in JSON format, you can utilize the Callbacks functionality or by sending a GET screening/{id} request to retrieve screening. However, for a more detailed report of a completed screening, please see the Reports section for receiving screening results in PDF or HTML formats.\n\n

Callback Types

\n\nThe callback `type` field supports future extensibility.\n\nAdditional 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 every other callback type that exists.\n\nAlternatively, 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.\n\n### Authentication\n\nBased on your security requirements, you may choose between Basic Auth or OAuth for your callback authentication. Basic Auth credentials can be used and implemented right away. If you want to utilize OAuth, you will need to reach out to your Sterling representative to enable this setting on your account. Once enabled, you can configure your callback uris and authentication via the /config/callbacks endpoint.\n\n#### Basic Auth for Callbacks\n\nBy default, all callback uris will use Basic Auth if you include the `credentials` object within the callback object of your screening requests. No Authentication will be used if you omit `credentials`. Refer to the [Credentials object](#4e499a0d-790e-410c-b077-500af60fcda6) section for more details.\n\n#### OAuth for Callbacks\n\nIf you choose to enable and configure OAuth for your callbacks, that configuration will take precedence over any other callback information sent in your screening requests.\n\n_Configure OAuth for Callbacks_\n\n``` plaintext\ncurl -X POST 'https://api.us.int.sterlingcheck.app/v2/config/callbacks' \\\n-H 'Authorization: Bearer {{bearer_token}}' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"callback\": {\n \"screening\": \"https://my-company-url.com\",\n \"monitor\": \"https://my-company-url.com\",\n \"oauth\": \"https://oauth-service.com/oauth2/token\" \n },\n \"grantType\": \"client_credentials\",\n \"oAuthCredentials\": \"\" \n}'\n\n ```\n\n| Attribute | Required | Type | Description |\n| --- | --- | --- | --- |\n| `callback` | required | object | |\n| `screening` | required
`screening` or `monitor` or both are required and cannot be omitted | string | A uri on a server that you control where you expect to receive callback updates related to screenings.
Must be an `https` uri. |\n| `monitor` | required (If using Sterling Monitoring)
`screening` or `monitor` or both are required and cannot be omitted | string | A uri on a server that you control where you expect to receive callbacks related to recurring monitoring updates.
Must be an `https` uri. |\n| `oauth` | required | string | This is the url of the service that generates the oAuth token for your callback authentication. |\n| `grantType` | required | string | The type of grant from your token generation service. |\n| `oAuthCredentials` | required | string | Base64 encoded credentials of your token generation service. Must be a Base64 encoded string in the format of `client_id:client_secret`. |\n\n_Errors_\n\nIf an error occurs when setting up OAuth for Callbacks you will receive an error code and mesage.\n\n**Examples**\n\n``` json\n{\n \"errors\": [\n {\n \"code\": \"400#callback-config?missing-callback-config-uris\",\n \"message\": \"At least one of CallbackConfigUris.screening or CallbackConfigUris.monitor has to be provided.\"\n }\n ]\n}\n\n ```\n\n``` json\n{\n \"errors\": [\n {\n \"code\": \"400#grantType\",\n \"message\": \"grantType is required\"\n }\n ]\n}\n\n ```\n\n### **Retries**\n\n> Callbacks will be retried exponentially starting at 15 minutes, 30 minutes, 1 hour, and so on until an HTTP 200 success response is returned from your server, or the time between attempts has reached 24 hours. \nYou also have the option to resend callbacks using our [POST /screenings/{id}/callbacks](#277b5ad3-f7c1-4e37-b212-1ac4987eee13) endpoint. While this gives you some control as to when callbacks are sent, you will only receive the most recent callback that was generated regardless of what the screening's current state is. \n \n\n### **Callback Success Acknowledgement**\n\n> When setting up your integration to accept callbacks from the Sterling API, you must return your success acknowledgement in the following JSON format with a status code of 200 or 201: `{“success”: ”true”}` \n \n\n#### Screening Callbacks\n\nThe 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.\n\n_Pending Screening Callback_\n\nWhen a screening status is first submitted, a callback containing a screening status of `Pending` will be sent. By default, the next callback for the screening will be sent once all report items are `Complete`.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"packageId\": \"85685\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"reportItems\": [],\n \"estimatedCompletionTime\": \"2021-05-30T16:21:00\"\n }\n}\n\n ```\n\nYour account can be configured to send Piecemeal callbacks. When enabled, callbacks for the `Pending` screening will be sent, listing the report items that are both Complete and still Pending.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"status\": \"Pending\",\n \"result\": \"Pending\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/HjlWtzer0dew8KpRBVudIBcS0dersaNcZQESRjBxhBM=\"\n }\n },\n \"customFields\": [\n {\n \"fieldName\": \"Job Opening ID\",\n \"fieldValue\": \"28374953\"\n },\n {\n \"fieldName\": \"Hiring Manager\",\n \"fieldValue\": \"Jane Doe\"\n },\n {\n \"fieldName\": \"Department\",\n \"fieldValue\": \"Engineering\"\n }\n ],\n \"reportItems\": [\n {\n \"id\": \"13993864\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Complete\",\n \"updatedAt\": \"2021-05-26T19:35:00\",\n \"estimatedCompletionTime\": \"2021-05-26T19:35:00\"\n },\n {\n \"id\": \"13993865\",\n \"type\": \"Enhanced Nationwide Criminal Search\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-05-26T19:36:00\",\n \"estimatedCompletionTime\": \"2021-05-26T19:36:00\"\n },\n {\n \"id\": \"13993866\",\n \"type\": \"County Criminal Record\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2021-05-30T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-30T16:21:00\"\n },\n {\n \"id\": \"13993867\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2021-05-28T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-28T16:21:00\"\n }\n ],\n \"submittedAt\": \"2021-05-26T19:34:57\",\n \"updatedAt\": \"2021-05-30T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-30T16:21:00\"\n }\n}\n\n ```\n\nIf the `estimatedCompletionTime` of a report item changes, a callback will be sent containing an updated dateTimeStamp. When ETA bumps like this occur, the callback will only contain the report item whose ETA changed.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"status\": \"Pending\",\n \"result\": \"Pending\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/HjlWtzer0dew8KpRBVudIBcS0dersaNcZQESRjBxhBM=\"\n }\n },\n \"reportItems\": [\n {\n \"id\": \"13993867\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2021-05-29T08:10:00\",\n \"estimatedCompletionTime\": \"2021-05-29T08:10:00\"\n }\n ],\n \"submittedAt\": \"2021-05-26T19:34:57\",\n \"updatedAt\": \"2021-05-29T08:10:00\",\n \"estimatedCompletionTime\": \"2021-05-29T08:10:00\"\n }\n}\n\n ```\n\n_Completed Screening Callback_\n\nA callback will be sent once all report items are completed and the screening status is `Complete`.\n\n> The `disposition` field will only be available if configured in your account. \n \n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"disposition\": \"Meets company standard\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/HjlWtzer0dew8KpRBVudIBcS0dersaNcZQESRjBxhBM=\"\n }\n },\n \"customFields\": [\n {\n \"fieldName\": \"Job Opening ID\",\n \"fieldValue\": \"28374953\"\n },\n {\n \"fieldName\": \"Hiring Manager\",\n \"fieldValue\": \"Jane Doe\"\n },\n {\n \"fieldName\": \"Department\",\n \"fieldValue\": \"Engineering\"\n }\n ],\n \"reportItems\": [\n {\n \"id\": \"13993864\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Complete\",\n \"updatedAt\": \"2021-05-26T19:35:00\",\n \"estimatedCompletionTime\": \"2021-05-26T19:35:00\"\n },\n {\n \"id\": \"13993865\",\n \"type\": \"Enhanced Nationwide Criminal Search\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-05-26T19:36:00\",\n \"estimatedCompletionTime\": \"2021-05-26T19:36:00\"\n },\n {\n \"id\": \"13993866\",\n \"type\": \"County Criminal Record\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-05-30T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-30T16:21:00\"\n },\n {\n \"id\": \"13993867\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-05-28T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-28T16:21:00\"\n }\n ],\n \"submittedAt\": \"2021-05-26T19:34:57\",\n \"updatedAt\": \"2021-05-30T16:21:00\",\n \"estimatedCompletionTime\": \"2021-05-30T16:21:00\"\n }\n}\n\n ```\n\n#### Consent Collection Callbacks\n\nYou may receive callbacks for important events related to the consent collections workflow. Consent collections callbacks should be registered using the `screening` callback type outlined in the _OAuth For Callbacks_ configuration above.\n\n_Consent Collection Initiated_\n\nWhen Sterling sends the invite, a callback with the status `InProgress` will indicate that the consent collection request has been submitted and the invite has been sent to the candidate.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"consent-collections\",\n \"payload\": {\n \"requestId\": \"dadccb11-d25f-4cb8-8c7c-8703f9188b07\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"InProgress\",\n \"submittedAt\": \"2025-01-22T18:19:00\",\n \"updatedAt\": \"2025-01-22T19:19:00\"\n }\n}\n\n ```\n\n_Consent Collection Completed_\n\nAfter the candidate reviews and signs the consent and authorization forms, and submits the invite workflow, a callback with the status `Complete` will be sent to indicate that the consent collection request has been completed.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"consent-collections\",\n \"payload\": {\n \"requestId\": \"dadccb11-d25f-4cb8-8c7c-8703f9188b07\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"Complete\",\n \"submittedAt\": \"2025-01-22T18:19:00\",\n \"updatedAt\": \"2025-01-22T19:19:00\"\n }\n}\n\n ```\n\n_Consent Collection Error_\n\nIf the consent collection request is not processed due to errors, a callback with status `Error` will be generated.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"consent-collections\",\n \"payload\": {\n \"requestId\": \"dadccb11-d25f-4cb8-8c7c-8703f9188b07\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"Error\",\n \"errors\": [\n {\n \"code\": \"400#dob?format\",\n \"message\": \"dob must be in the format of YYYY-MM-DD\"\n }\n ]\n }\n}\n\n ```\n\n_Expired Consent Collection Invite_\n\nIf the candidate misses or ignores the consent collection request and it expires, a callback with status `Expired Invite` will be generated.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"consent-collections\",\n \"payload\": {\n \"requestId\": \"dadccb11-d25f-4cb8-8c7c-8703f9188b07\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"Expired Invite\"\n }\n}\n\n ```\n\n#### Fulfillment Notes Callbacks\n\nFulfillment teams enter notes on an order for many different reasons. Your account can be configured to receive callbacks whenever a note is entered on an order, both at the search level and order level.\n\n_Order Level Note_ \n\nEvery time a note is saved on an order, a callback may be sent to you.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening-note\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"notes\": [\n {\n \"note\": \"Outbound E-mail|Candidate|Candidate Contacted. The email for 12-Sept-2025 was sent to the candidate about needed information.\",\n \"updatedAt\": \"2025-09-12T11:58:56\"\n }\n ]\n }\n}\n\n ```\n\n_Search Level Note_ \n\nEvery time a note is save on a report item, a callback may be sent to you.\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening-report-item-note\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"reportItems\": [\n {\n \"id\": \"22065126\",\n \"notes\": [\n {\n \"note\": \"Outbound E-mail|Candidate|Candidate Contacted. The email for 12-Sept-2025 was sent to the candidate about needed information.\",\n \"updatedAt\": \"2025-09-12T11:58:56\"\n }\n ]\n }\n }\n}\n\n ``` \n\n\n# Statuses & Results\n\nEvery screening will have a `status` property in its payload. The value of `status` will change depending on the status of each item in `reportItems`.\n\n_Screening Statuses_\n\n| Status | Description |\n| --- | --- |\n| `PreDraft` | Communication sent to candidate; Report will be in this state until the candidate has supplied and submitted from the Candidate Hub portal. |\n| `Draft` | Order has not been submitted and has not started processing. |\n| `NotStarted` | Invite sent to candidate, but candidate has not taken action yet. |\n| `InProgress` | Candidate has taken action on their invite and/or the order is processing. |\n| `Pending` | Processing. At least 1 report item within this package has a status of pending. |\n| `Complete` | Report is completed and ready for review. |\n| `ActionNeeded` | Action is needed to provide or correct data. |\n| `ReadyForReview` | Order is waiting to be reviewed. |\n| `Review` | Discrepancies found on one or more of the report items; A manual score or initiating Adverse Action is advised. |\n| `AdverseAction` | Report is in the Adverse Action process. |\n| `Pre-Adverse Action Initiated`, `Pre-Adverse Action Sent`, `Adverse Action Paused`, `Adverse Action Cancelled`, `Adverse Action Resumed`, `Adverse Action Sent` | Enhanced order scoring for the Adverse Action process - Please refer to our [Adverse Actions](#db918313-05bb-4d30-a043-8216d680a407) section for more details. |\n| `Dispute` | Candidate dispute in progress. |\n| `Archive` | Report has been archived. |\n| `Hold` | Report has been placed on a hold; Awaiting further action. |\n| `Pending Adjudication` | Only available if enhanced order scoring has been configured for Adverse Action on your account. |\n| `Expired Invite` | The invite has not been completed within the expiry window and has expired. A new invite should be sent to candidate. |\n| `Deleted` | Only available for order invites - The invite has been cancelled before any candidate action has been taken. |\n\n_Screening Results_\n\n| Result | Description |\n| --- | --- |\n| `Pending` | Processing. At least 1 report item within this package has a status of pending. |\n| `Clear` | Report is completed and ready for review. |\n| `Consider` | Discrepancies found in one or more report items. |\n| `Passed` | 2-score CMA - Report has passed all criteria. |\n| `Review` | 2-score CMA - Discrepancies found on one or more of the report items; A manual score or initiating Adverse Action is advised. |\n| `Cancelled` | Report has been cancelled. |\n| `Level1`, `Level2`, `Level3` | 3-score CMA - Customized scoring criteria. Please refer to our [CMA](#cma-client-matrix-application) section for more details. |\n\n_Screening subStatus_\n\nScreening callbacks may include an additional field for `subStatus` which provides further information during the order and invite process. Contact your Sterling representative if you would like this additional field enabled for your account.\n\n| subStatus | Description |\n| --- | --- |\n| `Pending` | Order has one or more services submitted for fulfillment that are not yet completed. |\n| `Dispute` | Candidate has filed a dispute, and it is in progress. If final Adverse Action has not been sent the search request will be moved to a Paused status |\n| `Hold` | The order and its fulfillment have been moved to Hold status. |\n| `Invite Queued` | An invite is created with all the necessary information but has not been sent. |\n| `Invite Sent` | The invite was sent successfully to the candidate. |\n| `Invite Incomplete` | Candidate has created an account but has not completed the consent and/or data collection process. |\n| `Invite Ready` | The candidate has successfully completed their Candidate Hub workflow. |\n| `Invite Data Mismatch` | Candidate has been successfully verified by the Identity Provider, but their information does not match what was submitted by the client when the invite was created. |\n| `Archived Invite` | Invite has been moved to an archived state either manually by the client or by an automated process. |\n| `Expired Invite` | Invite has expired and can no longer be accessed. |\n| `Cancelled Invite` | Invite was cancelled and can no longer be accessed. |\n| `Pre-Adverse Action Initiated` | Client has initiated the Pre-Adverse Action process but the email or postal mail has not yet been sent to the candidate. |\n| `Pre-Adverse Action Sent` | Client has initiated and the Pre-Adverse Action email or postal mail has been sent to the candidate. |\n| `Adverse Action Paused` | Adverse Action has been paused and a final Adverse Action notice will not be sent. |\n| `Adverse Action Resumed` | Adverse Action has been Resumed but the Final Adverse Action Notice has not been sent. |\n| `Adverse Action Sent` | Final Adverse Action has been sent to the candidate. |\n| `Archived Orders` | Order has been moved to an archived state either manually by the client or by an automated process. |\n| `Drafted Order` | An order has been created but no services have been submitted for fulfillment. |\n| `Candidate Action` | There is an open Additional/Missing information task for the candidate that must be completed before the order can be moved forward. |\n| `Client Action` | There is an open Additional/Missing information task for the client that must be completed before the order can be moved forward. |\n| `Fingerprint Submission Hold` | Candidate fingerprints have been received and are being held on file pending release by the client. |\n| `Verify Identity` | Order includes a UK criminal disclosure service with Client Evidence of Identify, and we are waiting for the client to verify the candidate’s identity. |\n\n_Report Item Statuses_\n\nEach individual report item may have their own statuses and these will vary upon the type of report processed.\n\nIf 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.\n\n| Status | Description |\n| --- | --- |\n| `Complete` | The report has been completed. |\n| `Pending` | The report is pending. |\n| `Deleted` | The report has been deleted. |\n| `Archive` | The report has been archived. |\n| `Cancelled` | Adverse Action has been cancelled on this report. |\n| `Paused` | Adverse Action process is paused for this report. |\n| `NeedsData` | The report needs additional information to proceed. |\n| `Ready` | The report is ready. |\n\n_Report Item Results_\n\nA report item's `result` property will give a more detailed description of the response.\n\n| Result | Description |\n| --- | --- |\n| `Clear` | Item is cleared and ready for review. |\n| `Consider` | Discrepancies found on the item and ready for review. |\n| `UnPerformable` | Item is unable to be performed. |\n| `Complete` | Item is completed and ready for review. |\n| `Passed` | 2-score CMA - Item has passed all criteria. |\n| `Review` | 2-score CMA - Discrepancies found on the item; A manual score or initiating Adverse Action is advised. |\n| `Cancelled` | Item has been cancelled. |\n| `Hold` | Item has been placed on a hold; Awaiting further action. |\n| `Level1`, `Level2`, `Level3` | 3-score CMA - Customized scoring criteria. Please refer to our [CMA](#cma-client-matrix-application) section for more details. |\n\n_Pending Screening Callback with subStatus_\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1812532311\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"InProgress\",\n \"subStatus\": \"Pending\",\n \"result\": \"\",\n \"customFields\": [\n {\n \"fieldName\": \"Job Opening ID\",\n \"fieldValue\": \"28374953\"\n },\n {\n \"fieldName\": \"Hiring Manager\",\n \"fieldValue\": \"Jane Doe\"\n },\n {\n \"fieldName\": \"Department\",\n \"fieldValue\": \"Engineering\"\n }\n ],\n \"reportItems\": [\n {\n \"id\": \"384835465\",\n \"type\": \"SSN Trace\",\n \"status\": \"Pending\",\n \"updatedAt\": \"2024-09-27T12:31:00\",\n \"estimatedCompletionTime\": \"2024-09-27T12:31:00\"\n },\n {\n \"id\": \"384835467\",\n \"type\": \"Enhanced Nationwide Criminal Search\",\n \"status\": \"Pending\",\n \"updatedAt\": \"2024-10-01T12:31:00\",\n \"estimatedCompletionTime\": \"2024-10-01T12:31:00\"\n },\n {\n \"id\": \"384835468\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Pending\",\n \"updatedAt\": \"2024-09-27T12:31:00\",\n \"estimatedCompletionTime\": \"2024-09-27T12:31:00\"\n }\n ],\n \"submittedAt\": \"2024-09-26T18:19:00\",\n \"updatedAt\": \"2024-10-01T19:19:00\",\n \"estimatedCompletionTime\": \"2024-10-01T19:19:00\"\n }\n}\n\n ```\n\n_Adverse Action Callback with subStatus_\n\n**JSON Example**\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1812532311\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"81dcf680-fdc2-44f7-b966-f5d6f48ce750\",\n \"status\": \"Pre-Adverse Action Sent\",\n \"subStatus\": \"Pre-Adverse Action Sent\",\n \"result\": \"Review\",\n \"customFields\": [\n {\n \"fieldName\": \"Job Opening ID\",\n \"fieldValue\": \"28374953\"\n },\n {\n \"fieldName\": \"Hiring Manager\",\n \"fieldValue\": \"Jane Doe\"\n },\n {\n \"fieldName\": \"Department\",\n \"fieldValue\": \"Engineering\"\n }\n ],\n \"reportItems\": [\n {\n \"id\": \"384835465\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"UnPerformable\",\n \"updatedAt\": \"2024-09-26T11:53:00\",\n \"estimatedCompletionTime\": \"2024-09-26T11:53:00\"\n },\n {\n \"id\": \"384835467\",\n \"type\": \"Enhanced Nationwide Criminal Search\",\n \"status\": \"Complete\",\n \"result\": \"Consider\",\n \"updatedAt\": \"2024-09-26T11:53:00\",\n \"estimatedCompletionTime\": \"2024-09-26T11:53:00\"\n },\n {\n \"id\": \"384835468\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Consider\",\n \"updatedAt\": \"2024-09-26T11:54:00\",\n \"estimatedCompletionTime\": \"2024-09-26T11:54:00\"\n },\n {\n \"id\": \"384835502\",\n \"type\": \"Managed Adverse Action\",\n \"status\": \"Pending\",\n \"updatedAt\": \"2024-10-03T11:57:00\",\n \"estimatedCompletionTime\": \"2024-10-03T11:57:00\"\n }\n ],\n \"submittedAt\": \"2024-09-26T11:52:00\",\n \"updatedAt\": \"2024-09-26T11:55:00\",\n \"estimatedCompletionTime\": \"2024-09-26T11:55:00\"\n }\n}\n\n ```\n\n_Verified Candidate Information_\n\nFor candidate verification, callbacks will be sent for the following occurrences.\n\n| Action | Received information in callback |\n| --- | --- |\n| Candidate completes ID.me process | Payload of screening with `Complete` status |\n| ID.me invite expires | Screening with `Expired Invite` status |\n\nTo see this reflected in the candidate, please refer to [GET /candidate/{id}](#902667-44ebb6bd-a36c-452d-8aea-272052cf8c85)\n\n**Callback Consumption**\n\n> 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. \n \n\n

Request for More Information

\n\nIn the event that a candidate's screening cannot move forward due to missing information, the Sterling API can send you a callback requesting you provide that data. To do so, you will need to [attach the requested documentation](#13e36b93-dd4b-4a9f-9deb-e4d76882d338) to the existing screening.\n\n_Missing Information_\n\nIn cases where information is missing which would prevent the screening from processing, a callback containing a field with `missingInformation` will be provided.\n\n> This callback will only contain the searches that require more information. \n \n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020633\",\n \"packageId\": \"85685\",\n \"packageName\": \"Basic Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"ec92a17b-7673-49ed-bdcc-b9991a5bbb78\",\n \"status\": \"Pending\",\n \"result\": \"Pending\",\n \"missingInformation\":\"Requested: ATTENTION CANDIDATES: If you'd like to speak with candidate support, please contact 833-780-7902 and then enter candidate code 1003.\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/HjlWtzer0dew8KpRBVudIBcS0dersaNcZQESRjBxhBM=\"\n }\n },\n \"reportItems\": [\n {\n \"id\": \"384186324\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Unperformable\",\n \"updatedAt\": \"2024-04-04T14:50:00\",\n \"estimatedCompletionTime\": \"2024-04-04T14:50:00\"\n },\n {\n \"id\": \"384186328\",\n \"type\": \"County Criminal Record\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2024-04-11T15:50:00\"\",\n \"estimatedCompletionTime\": \"2024-04-11T15:50:00\"\n }\n ],\n \"submittedAt\": \"2024-04-04T14:49:53\",\n \"updatedAt\": \"2024-04-11T15:50:00\",\n \"estimatedCompletionTime\": \"2024-04-11T15:50:00\"\n }\n}\n\n ```\n\n_Driver's Record Missing Information_\n\nPlease reach out to your account manager if you would like to enable this functionality on your account.\n\nIf your screening includes an MVR Driver's Record search and there is an issue with the candidate's license (i.e., Name mismatch or expired), then the report item in the provided callback will return a status of `NeedsData`.\n\nAfter you receive the callback, you will need to attach a copy of the candidate's current driver's license to their screening. Once attached, fulfillment will be able to review and process the order.\n\n``` json\n{\n \"reportItems\": [\n {\n \"id\": \"13804226\",\n \"type\": \"Drivers Record\",\n \"status\": \"NeedsData\",\n \"result\": \"\",\n \"updatedAt\": \"2021-05-07T16:52:00\"\n }\n ]\n}\n\n ```\n\n

Driver's License State Mismatches

\n\nWhen creating a new screening that includes an MVR report, the API can indicate whether a candidate's primary address matches the state their driver's license was issued from or not.\n\nIn the event that there is a mismatch, a new `dlStateMismatch` field should appear under the MVR report item within the screening response. Your callbacks will also include this new field.\n\nIf there is a match, the `dlStateMismatch` field will not appear.\n\n``` json\n\"reportItems\": [\n {\n \"id\": \"14498557\",\n \"type\": \"Drivers Record\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-11-30T16:45:00\",\n \"estimatedCompletionTime\": \"2021-11-30T16:45:00\",\n \"dlStateMismatch\": true\n },...\n]\n\n ```\n\n# Verified Candidate Data\n\nWhen verifying candidate data, first create a screening with an ID.me product. In the request payload, you can specify whether the ID.me invitation will be sent via link or email.\n\nOnce the ID.me process is in `complete` status, a callback will be received, and you can also check that the candidate information has been updated at GET /candidates/{id}.\n\n# Progressive Ordering\n\nProgressive packages are configured by Sterling to automatically run each search or sets of searches in phases, gating the launch of a phase when a potentially disqualifying hit is found.\n\nYou can launch progressive orders by submitting a package ID with your screening request. If your account is set up with these packages, you may need to make changes on how you handle callbacks.\n\n**Example**\n\nThe package below is set up progressively so that the searches within the profiles are launched in order. Profiles can have multiple searches in which they all will need to clear to move onto the next profile.\n\n**Note:** The results shown in the examples below may differ based on your account’s [CMA](#cma-client-matrix-application) configuration.\n\n_Progressive Package_\n\n- Profile 1: SSN Trace\n \n- Profile 2: DOJ Sex Offender Search\n \n- Profile 3: County Criminal Search\n \n\n_Creating a New Screening_\n\nCreating a new screening using the above package will return the first profile in the report items. You will not receive a callback until every search within their respective profile is completed.\n\n``` json\n{\n \"id\": \"1801113318\",\n \"packageId\": \"186668\",\n \"packageName\": \"Progressive Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"18401bf8-eb88-41fb-8636-a194507052b6\",\n \"status\": \"Pending\",\n \"result\": \"Pending\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/order-hash\"\n }\n },\n \"callback\": {\n \"uri\": \"https://my-company.com/screenings-callback\"\n },\n \"reportItems\": [\n {\n \"id\": \"14159019\",\n \"type\": \"SSN Trace\",\n \"status\": \"pending\",\n \"result\": null,\n \"updatedAt\": \"2021-06-07T17:10:00Z\",\n \"estimatedCompletionTime\": \"2021-06-07T17:10:00Z\"\n }\n ],\n \"submittedAt\": \"2021-06-04T16:10:25Z\",\n \"updatedAt\": \"2021-06-07T17:10:00Z\",\n \"estimatedCompletionTime\": \"2021-06-07T17:10:00Z\"\n}\n\n ```\n\n_Profile 1 Completes; Callback Notification Sent_\n\nAfter the first profile is completed and cleared, the set of searches for profile 2 are launched. In this example the candidate has an alias, so an additional search is added. The rest of the callback payload has been trimmed down to just the report items for this example.\n\n``` json\n\"reportItems\": [\n {\n \"id\": \"14159019\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Complete\",\n \"updatedAt\": \"2021-06-04T12:11:00\"\n },\n {\n \"id\": \"14159020\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2021-06-07T13:11:00\"\n },\n {\n \"id\": \"14159021\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Pending\",\n \"result\": \"\",\n \"updatedAt\": \"2021-06-07T13:11:00\"\n }\n]\n\n ```\n\n_Hit is Found; Screening is Halted and Scored for Review_\n\nAs this search progresses a hit is found in the current profile. The screening’s `status` is set to `Complete` and scored based off the search results up to that point. The next step for screenings in this situation is for your Operations team to review and determine whether [Adverse Action](#db918313-05bb-4d30-a043-8216d680a407) is required or if the searches can resume.\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801113318\",\n \"packageId\": \"186668\",\n \"packageName\": \"Progressive Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"18401bf8-eb88-41fb-8636-a194507052b6\",\n \"status\": \"Complete\",\n \"result\": \"Consider\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/order-hash\"\n }\n },\n \"reportItems\": [\n {\n \"id\": \"14159019\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Complete\",\n \"updatedAt\": \"2021-06-04T12:11:00\"\n },\n {\n \"id\": \"14159020\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-06-04T12:38:00\"\n },\n {\n \"id\": \"14159021\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Consider\",\n \"updatedAt\": \"2021-06-04T12:38:00\"\n }\n ],\n \"submittedAt\": \"2021-06-04T12:10:25\",\n \"updatedAt\": \"2021-06-04T12:45:00\"\n }\n}\n\n ```\n\n_Screening Completes_\n\nIf your Operations team decides to continue the progressive workflow, the screening will resume onto the next profiles. Like any other report, the overall result is based off all the collective search results.\n\nIn this example, the order score has been changed to `Clear` because the offending search was acceptable in this test scenario. Otherwise, you would see `Consider` returned as a result. Any report items that had hits will keep their existing result because search-level scores cannot be changed by users, only the order-level score.\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801113318\",\n \"packageId\": \"186668\",\n \"packageName\": \"Progressive Package\",\n \"accountName\": \"Sterling API Test\",\n \"accountId\": \"12345\",\n \"candidateId\": \"18401bf8-eb88-41fb-8636-a194507052b6\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/order-hash\"\n }\n },\n \"reportItems\": [\n {\n \"id\": \"14159019\",\n \"type\": \"SSN Trace\",\n \"status\": \"Complete\",\n \"result\": \"Complete\",\n \"updatedAt\": \"2021-06-04T12:11:00\"\n },\n {\n \"id\": \"14159020\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-06-04T12:38:00\"\n },\n {\n \"id\": \"14159021\",\n \"type\": \"DOJ Sex Offender Search\",\n \"status\": \"Complete\",\n \"result\": \"Consider\",\n \"updatedAt\": \"2021-06-04T12:38:00\"\n },\n {\n \"id\": \"14159063\",\n \"type\": \"County Criminal Record\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-06-04T13:07:00\"\n },\n {\n \"id\": \"14159064\",\n \"type\": \"County Criminal Record\",\n \"status\": \"Complete\",\n \"result\": \"Clear\",\n \"updatedAt\": \"2021-06-04T13:07:00\"\n }\n ],\n \"submittedAt\": \"2021-06-04T12:10:25\",\n \"updatedAt\": \"2021-06-04T13:09:00\"\n }\n}\n\n ```\n\n**Testing**\n\n> We advise testing any new progressive packages to get a better feeling for how they work. You will need to determine what business logic needs to be in place after each search is completed and how to handle any callbacks that return hits. \n \n\n# Asynchronous Processing\n\nTo continue supporting our clients’ need for faster and more reliable screening response times, Sterling now has the ability to allow for asynchronous order processing. This will allow Sterling to serve large volume clients more effectively by improving our ability to handle spikes in order volume. With this update, the Sterling API will provide immediate acknowledgment of order acceptance while the order is processing. This is a client-level feature and cannot be customized per package or workflow.\n\nThe default ordering behavior for all clients is synchronous processing. To enable the asynchronous ordering process, contact your Sterling representative.\n\n## Overview\n\nOnce enabled, the existing Create Screening call will remain a synchronous process until a configurable timeout duration is reached. Once the timeout threshold is reached, a success code of 202 Accepted will be returned. The request will be queued in Sterling and send back an asynchronous response once the screening request has been processed.\n\nIn the case of an asynchronous 202 Accepted response, the body of the response will contain an Order ID, Candidate ID, and a “status” field with the value “Queued”. The Order ID and Candidate ID will not change throughout the entire process and both can be used as lookup identifiers in the endpoints listed. Once processing is completed for the order, a callback notification will be sent with the updated order status, containing the same values as the current successful synchronous response.\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020641\", \n \"accountId\": \"12345\", \n \"candidateId\": \"3e4f84e3-9078-4451-a8b8-5897f4f4f4e3\",\n \"status\": \"Queued\",\n \"result\": \"Pending\"\n \"callback\": {\n \"uri\": \"https://my-company.com/screenings-callback\"\n },\n \"updatedAt\": \"2023-03-16T00:02:00Z\"\n}\n\n ```\n\n_Errors:_\n\nIf an error occurs in the asynchronous process, a callback notification with a payload containing details of the error will be sent to the callback listener. The error callback will contain an error code and error message.\n\n``` json\n{\n \"type\": \"screening\",\n \"payload\": {\n \"id\": \"1801020641\", \n \"accountId\": \"12345\", \n \"candidateId\": \"3e4f84e3-9078-4451-a8b8-5897f4f4f4e3\",\n \"packageId\": \"419094\",\n \"status\": \"Error\",\n \"result\": \"NA\",\n \"errors\": [\n {\n \"code\": \"400#dob?format\",\n \"message\": \"dob must be in the format of YYYY-MM-DD\"\n }\n ]\n \"updatedAt\": \"2023-03-16T00:02:00Z\"\n }\n}\n\n ```\n\nIf a GET /screening/{id} call is made for a screening that failed in the asynchronous process, an error code and error message will be given in the response.\n\n``` json\n{\n \"errors\": [\n {\n \"code\": \"410 \",\n \"message\": \"Order creation failed\"\n }\n ]\n}\n\n ```\n\n# Á la carte Ordering\n\nAdditional functionality has been added to support ordering products á la carte instead of ordering an entire screening package. To use this functionality, your account will need to be configured with á la carte products. Contact your Sterling representative for configuration.\n\nA candidate ID must be created before requesting an á la carte order for the candidate. You can retrieve all available á la carte products via the [/products](#2df571c1-b1e7-42dd-b04c-48bbe989e3d5) endpoint. You'll need to pass the `root` and `description` values from the [/products/{productCode}/variants](#bcbbce8f-7a97-470e-85ee-cda3e62e830e) endpoint in your á la carte screening request.\n\n> Currently the only supported á la carte offering is Registered Drug Tests. A la carte RDT is not available in Canada, EMEA or APAC. \n \n\n_Creating a New Á la carte Screening_\n\n``` json\n{\n \"candidateId\": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\",\n \"alacarte\": [\n {\n \"product\": \"RDT\",\n \"root\": \" DHS100000\",\n \"description\": \"Urine: 10 Panel\"\n },\n {\n \"product\": \"RDT\",\n \"root\": \"DHS30056\",\n \"description\": \"Clinical: Hepatitis A Titer (Blood)\"\n }\n ],\n \"drug\": {\n \"sex\": \"male\",\n \"reasonForTest\": \"Return_To_Duty\",\n “applicantCopy”: true,\n \"clientCopy\": true,\n \"clientCopyEmailList\":\"xxx.xxx@gmail.com, yyy.123@mycompany.com\",\n \"siteSelectionAddress\": {\n \"addressLine\": \"222333 PEACHTREE PLACE\",\n \"municipality\": \"ATLANTA\",\n \"regionCode\": \"US-GA\",\n \"postalCode\": \"30318\",\n \"countryCode\": \"US\"\n }\n },\n \"customFields\": [\n {\n \"fieldName\": \"Custom Field One\",\n \"fieldValue\": \"123456\"\n },\n {\n \"fieldName\": \"Custom Field Two\",\n \"fieldValue\": \"AAAAAAA\"\n }\n ],\n \"callback\": {\n \"uri\": \" https://my-company.com/screenings-callback\",\n \"credentials\": {\n \"basic-auth\": \"base-64-encoded-credentials\"\n }\n }\n}\n\n ```\n\n_Á la carte Screening Request is Successful_\n\n``` json\n{\n \"id\": \"1803082004\",\n \"candidateId\": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\",\n \"status\": \"Pending\",\n \"result\": \"Pending\",\n \"customFields\": [\n {\n \"fieldName\": \"Custom Field One\",\n \"fieldValue\": \"123456\"\n },\n {\n \"fieldName\": \"Custom Field Two\",\n \"fieldValue\": \"AAAAAAA\"\n }\n ],\n \"links\": {\n \"admin\": {\n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/Y2sza1BuY0tQR2V6SlVEUkJMOXFZQT09/?type=base64Url\"\n }\n },\n \"callback\": {\n \"uri\": \" https://my-company.com/screenings-callback\"\n },\n \"reportItems\": [\n {\n \"id\": \"16665554\",\n \"type\": \"Drug & Health Test\",\n \"status\": \"pending\",\n \"result\": null,\n \"root\": \"DHS100000\",\n \"description\": \"Urine: 10 Panel\",\n \"updatedAt\": \"2023-07-04T22:27:00Z\",\n \"estimatedCompletionTime\": \"2023-07-04T22:27:00Z\"\n },\n {\n \"id\": \"16665555\",\n \"type\": \"Drug & Health Test\",\n \"status\": \"pending\",\n \"result\": null,\n \"root\": \"DHS30056\",\n \"description\": \"Clinical: Hepatitis A Titer (Blood)\"\n \"updatedAt\": \"2023-07-04T22:27:00Z\",\n \"estimatedCompletionTime\": \"2023-07-04T22:27:00Z\"\n }\n ],\n \"submittedAt\": \"2023-06-29T21:27:10Z\",\n \"updatedAt\": \"2023-07-04T22:27:00Z\",\n \"estimatedCompletionTime\": \"2023-07-04T22:27:00Z\"\n}\n\n ```\n\n_Errors_\n\n| HTTP Code | Error Code | Error Message |\n| --- | --- | --- |\n| 400 | `400#alaCarte?not-found` | A la carte product information not found/configured |\n| 400 | `400#drug.reasonForTest` | if drug is provided, reasonForTest is required |\n| 400 | `400#required-field` | Alacarte product(s) require field ssn |\n| 400 | `400#drug.siteSelectionAddress.postalCode` | if drug.siteSelectionAddress is provided, postalCode is required |\n| 422 | `422#orderType?unprocessable` | One of either package ID or a la carte information is required to process this screening |\n| 422 | `422#screening?unprocessable` | One or several products not supported by Alacarte |\n| 500 | `500` | Client copy is true but client copy email list is empty. |\n\n# Sterling Monitoring\n\nSterling offers robust and compliant criminal and MVR monitoring options. Reach out to your Sterling representative to select the service(s) that best meets your business needs. Once your account is configured for monitoring, you will enroll your candidates in the monitoring program, then receive validated results in Sterling Platform.\n\nA candidate ID must be created before enrolling the record in the monitoring program. You will also receive a UUID from Sterling for your monitoring subscription.\n\n**Required Fields** \nTo enroll a candidate in monitoring, the following fields must first be created on the candidate record:\n\n- `givenName`\n \n- `familyName`\n \n- `ssn`\n \n- `dob`\n \n- `address`\n \n - `addressLine`\n \n - `municipality`\n \n - `postalCode`\n \n - `countryCode`\n \n - `regionCode`\n \n\nFor MVR monitoring, Drivers License information is also required:\n\n- `driversLicense`\n \n - `type`\n \n - `licenseNumber`\n \n - `issuingAgency`\n \n\n_Enroll a candidate_\n\n``` json\n{\n \"transactionId\": \"123456789010\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId\": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\", \n \"disclosureAndAuthorisation\": true, \n \"certification\": true, \n \"callback\": { \n \"status\":{ \n \"uri\": \"https://my-company.com/monitoring-status-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n }, \n \"result\": { \n \"uri\": \"https://my-company.com/monitoring-result-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n } \n },\n \"additionalInfo\": [\n {\n \"name\": \"isUnincorporatedLACounty\",\n \"value\": \"false\"\n }\n ]\n}\n\n ```\n\n_Successful Enrollment Request_\n\nYou will immediately receive a response as Sterling processes the enrollment request. If there are no issues with the enrollment request, you will see `accepted` in the `status` field.\n\n``` json\n{\n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"status\": \"accepted\", \n \"transactionId\": \"123456789010\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\", \n \"callback\": { \n \"status\":{ \n \"uri\": \"https://my-company.com/monitoring-status-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n }, \n \"result\": { \n \"uri\": \"https://my-company.com/monitoring-result-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n } \n } \n}\n\n ```\n\n_Enrollment Status_\n\nUpon successful processing of the candidate's enrollment, you will receive an enrollment status callback to the `callback.status` url specified in the enrollment request. The `status` field will signal if the enrollment was successful or if any errors were encountered. If you unenroll your candidate from the monitoring program, you will also receive a status callback once the unenrollment has been processed.\n\n> The `monitorId` field is used to identify your candidate's monitoring enrollment. It is required should you decide to unenroll the candidate from the monitoring program. \n \n\nCandidate is enrolled:\n\n``` json\n{ \n \"type\": \"monitor\",\n \"payload\": { \n \"monitorId\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\", \n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"status\": \"enrolled\", \n \"statusMessage\": \"success\",\n \"transactionId\": \"123456789010\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\",\n \"callback\": { \n \"status\":{ \n \"uri\": \"https://my-company.com/monitoring-status-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n }, \n \"result\": { \n \"uri\": \"https://my-company.com/monitoring-result-callback\", \n \"credentials\": { \n \"basic-auth\": \"base64-encoded-credentials\" \n } \n } \n } \n } \n}\n\n ```\n\nIssue with enrollment:\n\n``` json\n{ \n \"type\": \"monitor\",\n \"payload\": { \n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"status\": \"error\", \n \"statusMessage\": \"error-message\",\n \"errorCode\": \"400#[resource].[field]\",\n \"transactionId\": \"123456789010\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\" \n } \n}\n\n ```\n\n| Field | Required | Type | Description |\n| --- | --- | --- | --- |\n| `monitorId` | No (will not be present if the enrollment status is `error` | string | The monitor identifier. |\n| `statusId` | Yes | string (uuid) | The unique identifier for the candidate’s monitor request. This is not the monitorId. This id is used to ensure uniqueness for correlation on the async status callback. |\n| `status` | Yes | string | The status the monitoring request. Options: `accepted`, `enrolled`, `unenrolled`, `error`. |\n| `statusMessage` | Yes | string | Context on why the monitor request succeeded or failed to process. |\n| `errorCode` | No (will not be present if the enrollment status is `enrolled` or `accepted` | string | Error code for business validation errors. |\n| `transactionId` | No | string | The client’s unique internal identifier. |\n| `subscriptionId` | Yes | string | The package equivalent for the monitoring subscription. |\n| `candidateId` | Yes | string (uuid) | The same candidateId used for the initial background check. |\n| `accountId` | Yes | string | Sterling Platform account ID; the enrollment will be associated to this account for access & billing purposes. |\n\n_Recurring Check Updates_\n\nCounty Criminal recurring checks are based on the free county list managed by Sterling. As an enrollee's recurring check schedule elapses, the decision to run a US County Criminal request will be sent to you in real-time. A `checkExecuted` status will be delivered to you on a regular basis throughout the year.\n\nCheck is not executed:\n\n``` json\n{ \n \"type\": \"recurring-check\", \n \"payload\": { \n \"monitorId\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\", \n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"productCode\": \"county-criminal\", \n \"checkExecuted\": false, \n \"message\": \"Did not execute, not a free county\" \n }\n}\n\n ```\n\nCheck is executed:\n\n``` json\n{ \n \"type\": \"recurring-check\", \n \"payload\": { \n \"monitorId\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\", \n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"productCode\": \"county-criminal\", \n \"checkExecuted\": true\n }\n}\n\n ```\n\n| Field | Required | Type | Description |\n| --- | --- | --- | --- |\n| `monitorId` | Yes | string | The monitor identifier. |\n| `statusId` | Yes | string (uuid) | The unique identifier for the candidate’s monitor request. This is not the monitorId. This id is used to ensure uniqueness for correlation on the async status callback. |\n| `candidateId` | Yes | string (uuid) | The candidateId used while placing the monitoring request |\n| `accountId` | Yes | string | Sterling Platform account ID; the enrollment will be associated to this account for access & billing purposes. |\n| `subscriptionId` | Yes | string | The package equivalent for the monitoring subscription. |\n| `productCode` | Yes | string | Product codes which are part of subscription |\n| `checkExecuted` | Yes | boolean | If `true`, a recurring check was completed successfully. If `false`, the county is not a free county or any other error while running recurring check. |\n| `message` | No | string | Detailed message when recurring check is not executed successfully due to free county or any other reason |\n\n_Monitoring Result Callback_\n\nIn the event a hit is found, Sterling's monitoring service will create a screening request to validate the hit and you will receive a result callback. Only callbacks for completed screenings with a `Consider` result will be sent.\n\n``` json\n{ \n \"type\": \"screening\", \n \"payload\": { \n \"id\": \"1801020633\", \n \"packageId\": \"\", \n \"accountName\": \"Employer Test Account\", \n \"accountId\": \"123456\", \n \"billCode\": \"\", \n \"jobPosition\": \"A'la Carte\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId\": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"monitorId\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\", \n \"status\": \"Complete\", \n \"result\": \" Consider\", \n \"links\": { \n \"admin\": { \n \"web\": \"https://int.sterlingcheck.app/interactive-summary/#/order/HjlWtzer0dew8KpRBVudIBcS0dersaNcZQESRjBxhBM=\" \n } \n }, \n \"customFields\": [\n {\n \"fieldName\": \"Monitor ID\",\n \"fieldValue\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\"\n },\n {\n \"fieldName\": \"Requested By\",\n \"fieldValue\": \"API User\"\n },\n {\n \"fieldName\": \"Monitoring Product Code\",\n \"fieldValue\": \"CRFM\"\n },\n ],\n \"reportItems\": [ \n { \n \"id\": \"13993865\",\n \"type\": \"County Criminal Search\", \n \"root\": \"OR\", \n \"description\": \"JACKSON\", \n \"status\": \"Complete\", \n \"result\": \"Consider\", \n \"updatedAt\": \"2024-03-26T19:36:00\", \n \"estimatedCompletionTime\": \"2024-03-26T19:36:00\" \n } \n ], \n \"submittedAt\": \"2024-03-26T19:34:57\", \n \"updatedAt\": \"2024-03-26T19:36:00\" \n } \n}\n\n ```\n\n| Field | Required | Type | Description |\n| --- | --- | --- | --- |\n| `id` | Yes | String | Background screening id for validated hit. |\n| `packageId` | Yes | String | The package ID used in background screening for validated hit. May be blank/null as monitoring hits are created a la carte. |\n| `packageName` | No | String | The package name used in background screening for validated hit. May be blank/null since monitoring hits are created a la carte. |\n| `accountName` | Yes | String | The account name used in the background screening. ex. “\\[Client Name\\] Monitoring Account” |\n| `accountId` | No | String | Sterling Platform account ID; the enrollment will be associated to this account for access & billing purposes. |\n| `billCode` | Yes | String | Bill Code associated with the screening. May be blank/null if bill codes are not configured or if the hit is not associated with a bill code. |\n| `jobPosition` | Yes | String | Job Position associated with the screening. |\n| `subscriptionId` | Yes | String | The package equivalent for the monitoring subscription. |\n| `candidateId` | Yes | String | The same candidateId used for the initial background check. |\n| `monitorId` | Yes | String | The monitor identifier. |\n| `status` | Yes | String | The status of the background check screening. |\n| `result` | Yes | String | The result of the background check screening. |\n| `links.admin.web` | Yes | String | Web link for client admins to login and view the background screening details. |\n| `customFields` | Yes | list | Custom field for \"Monitor ID\" will always be included. Additional custom fields may be available if configured in the account. |\n| `reportItems` | Yes | list | Report Item details of the background screening. |\n| `submittedAt` | Yes | String | Date and time at which the background screening was submitted. |\n| `updatedAt` | Yes | String | Date and time at which the background screening was updated. |\n| `estimatedCompletionTime` | Yes | String | Date and time at which the background screening was completed. |\n\n_Candidate PII Updates_\n\nWhile a candidate is enrolled in monitoring, updates to `givenName`, `familyName`, `middleName`, `address`, `licenseNumber` or `issuingAgency` will affect their monitoring enrollment. If any of these fields are updated via PUT /candidates/{id}, Sterling will automatically unenroll the existing monitor for the candidate and trigger a new monitoring enrollment. \nA status callback will be posted back with a status of \"unenrolled\" for the existing `monitorId`. A second status callback will be posted back with a status of \"enrolled\" and a new `monitorId`. Any future updates regarding monitoring for this candidate will be sent against the new `monitorId`.\n\n_California_\n\nIf a hit is found for a candidate living in California, Sterling will automatically unenroll them. The hit will be validated and a result callback will be sent. You will also receive a status callback with a status of \"unenrolled\". If you want to re-enroll the candidate, you will need to collect consent again and make a new enrollment request. Any new monitoring events will be sent against the candidate's new `monitorId`.\n\nCalifornia candidate is unenrolled:\n\n``` json\n{ \n \"type\": \"monitor\",\n \"payload\": { \n \"monitorId\": \"790f023a-e269-4650-8cd6-7b68dc0136c3\", \n \"statusId\": \"1e8dfd89-a57b-49c4-bb58-6f348f8f2bc0\", \n \"status\": \"unenrolled\", \n \"statusMessage\": \"New consent and enrollment required\",\n \"transactionId\": \"123456789010\", \n \"subscriptionId\": \"74f535f6-a622-49ce-8ac1-8b6bbffae21c\", \n \"candidateId \": \"4eee84f0-93c5-4452-91ee-fd891cb67ee0\", \n \"accountId\": \"123456\" \n } \n}\n\n ```\n\n# Idempotency\n\nThe Sterling API supports the use of an `idempotency-key` in your screening requests, which allows you to safely retry these requests without accidentally performing the same operation twice. This is helpful if there are networking issues and you wanted to guarantee that you do not create duplicate screenings.\n\nAn idempotency key can be unique value of your choice and how you create these keys is up to you. To avoid collisions within your own account, try using unpredictable string values or a random V4 UUID.\n\nIf a screening request fails when using the `idempotency-key`, retry using the same key value in order to guarantee that only one screening is created.\n\n**Key Expiration**\n\n> Any value used as an idempotency key to successfully create a new screening may be reused for **24 hours** after it is successfully associated with a screening record. Retrying screening attempts using the same key will not reset the expiration date and will continue to return the same screening associated with that key until the 24 hour expiration window is met. After the 24 hour window has passed, a new screening can and will be created with the same idempotency key. \n \n\n**cURL**\n\n```\ncurl -X POST 'https://api.us.int.sterlingcheck.app/v2/screenings' \\\n-H \"Authorization: Bearer \" \\\n-H 'Content-Type: application/json' \\\n-H 'idempotency-key: \"ccf492f0-231a-45eb-bc29-8e3687445715\"' \\\n-d '{\n \"packageId\": \"96193\",\n \"candidateId\": \"001c8b73-4b0d-4dac-bcc0-479bf91f222a\" \n}'\n\n ```\n\n# Errors\n\n

Overview

\n\nSterling uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate a success, codes in the `4xx` range indicate a request that failed given the information provided (e.g. a required parameter was omitted, format issues, etc.), and codes in the `5xx` range indicate an error with Sterling's servers.\n\nWhen a request is valid but does not complete successfully, we return a `400#` error code. Below you'll find more detailed information about the possible errors you can expect.\n\n

Error Format

\n\nThe expected format for an error is as follows:\n\n``` json\n{\n \"errors\": [\n {\n \"code\": \"400#dob?format\",\n \"message\": \"dob must be in the format of YYYY-MM-DD\"\n }\n ]\n}\n\n ```\n\nThe expected _code_ format is as follows, using \"400#dob?format\" as an example:\n\n- HTTP error code (400)\n \n- Optional offending field when relevant (dob)\n \n- Optional brief message when applicable (format)\n \n\n

Error Codes

\n\nSome common error codes include:\n\n

Candidate Validation Errors

\n\n| Code | Reason |\n| --- | --- |\n| 400#address.\\[field\\] | The address block is present, but missing a required address field such as “addressLine”. All required address fields missing from the submitted candidate data will each be noted in a separate “message” string in an array of the error response block. |\n| 400#additionalAddresses\\[i\\].\\[field\\] | The additionalAddresses block is present, but the ith address in the list is missing a required address field such as “addressLine”. All required additionalAddress fields missing from the submitted candidate data will each be noted in a separate “message” string in an array of the error response block. |\n| 400#driversLicense.\\[field\\] | The driversLicense block is present, but missing a required field such as \"licenseNumber\". All required driversLicense fields missing from the submitted candidate data will each be noted in a separate “message” string in an array of the error response block. |\n| 409#clientReferenceId?already-in-use | The given clientReferenceId is already in use. |\n| 409#email?already-in-use | The given email is already in use. |\n\n

Format Validation Errors

\n\n| Code | Reason |\n| --- | --- |\n| 400#?format | A given candidate field is not in the correct format, such as “dob” `YYYY-MM-DD`. |\n| 400#address.\\[field\\]?format | A given candidate address field such as “postalCode” is not in the correct format. |\n| 400#driversLicense.\\[field\\]?format | A given candidate driver’s license field such as “licenseNumber” is not in the expected format. |\n\n

Screening Errors

\n\n| Code | Reason |\n| --- | --- |\n| 400#candidateId?not-found | The given candidateId must be valid and associated with the authenticated account. |\n| 400#packageId?not-found | The packageId must be an active packageId associated with the authenticated account. |\n| 400#documentType | The documentType must be one of: \\[end-user-agreement, disclosure-and-authorization\\]. |\n| 400#screening?required-data | There is missing information on the screening request. This could range from an incomplete address block that was supplied for the candidate to attempting to enter in invalid custom fields in the screening. |\n| 400#required-field | There is missing information in the candidate record which is preventing the screening to process. You should update the candidate record with the missing data via [PUT /candidates/{id}](#e50ebaba-f0d8-4cc0-a3f9-43e3ccbabba1) request. |\n| 400#callback.uri?format | A callback.uri must be in a valid HTTPS URL format. |\n\n

Monitoring Errors

\n\nThese are the most common errors for Sterling Monitoring.\n\n| HTTP Code | Error Code | Error Message |\n| --- | --- | --- |\n| 400 | `400#{{fieldName}}` | {{fieldName}} is required |\n| 400 | `400#{{fieldName}}?format` | Invalid {{fieldName}} format |\n| 400 | `400#candidateId?not-found` | Candidate information not provided |\n| 400 | `400#candidate?{{fieldName}}` | {{fieldName}} is a required field of the candidate information |\n| 400 | `400#candidate?{{fieldName}}` | The {{fieldName}} length exceeds the maximum length {{maxlength}} |\n| 400 | `400#invalid-address` | Invalid address |\n| 400 | `403#already-enrolled` | Candidate already enrolled in monitoring |\n| 403 | `403#certification?not-provided` | Client certification not acknowledged |\n| 403 | `403#disclosureAndAuthorisation?not-provided` | Monitoring consent not Provided |\n| 403 | `403#unenrolled` | Candidate already unenrolled/not enrolled in monitoring |\n\n

Rate Limiting

\n\nWe hold ourselves to a high standard – and part of that means continuing to provide quality service to all customers. In order to make this is possible, the Sterling API is rate limited.\n\nIf you require higher rate limits, reach out to your Sterling representative and we may be able to accommodate.\n\nIf the rate limit is exceeded for the specified endpoint in your request, the API will respond with a `429 Too Many Requests` status code.\n\nBelow is a table of the rate limiting thresholds for the most used endpoints:\n\n| Endpoint | Requests / 5 Minute Period |\n| --- | --- |\n| POST /oauth | 125 |\n| POST /candidates | 300 |\n| GET /candidates/{id} | 300 |\n| POST /screenings | 300 |\n| GET /screenings/{id} | 300 |\n| POST /monitors | 500 |\n| DEL /monitors/{id} | 500 |\n\n

Controlling Your Requests

\n\nThere are several ways you can help control the amount of requests you make within limits:\n\n- If you believe there is a possibility that the limits could be exceeded, it is advised that you use exponential backoff logic to retry the requests.\n \n- If processing a large batch of requests, you could implement a delay between requests.\n \n- Check your existing workflow for duplicate or unnecessary API requests.\n \n- Use callbacks to receive real-time updates about a report instead of retrieving them in batches.\n \n\n# Versioning\n\nThis document describes the Sterling API. The Sterling API follows semantic versioning, which means that we are committed to maintaining this API without breaking changes. It considers any removal or renaming of an API endpoint or JSON field from an API response to be a breaking change. Additions of new _required_ input fields would also be incompatible with existing client code, so any newly-added input fields will always be optional.\n\nAlthough fields will not be _removed_ from responses, fields may be added to introduce new capabilities. Applications consuming this API should use permissive deserialization techniques when parsing JSON responses. It will always be safe to ignore unrecognized, optional fields.\n\n**Example of Permissive Deserialization**\n\n> When using the Jackson JSON parsing library for Java, clients should disable the `DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES` flag.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"7075989","team":319436,"collectionId":"6bb7ca94-07a0-4e4d-9423-38f2f6b03a77","publishedId":"TVRkZ7pA","public":true,"publicUrl":"https://apidocs.sterlingcheck.app","privateUrl":"https://go.postman.co/documentation/7075989-6bb7ca94-07a0-4e4d-9423-38f2f6b03a77","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"005656"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/095f1f08-ba60-4d34-b8e6-d357107b81e5/RkFfRnVsbExvZ29fSG9yaXpfV2hpdGVfUkdCLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"02E28B"}},{"name":"light","logo":"https://content.pstmn.io/c6ab5416-91b0-4d4f-9371-d7101a30f47b/RkFfRnVsbExvZ29fSG9yaXpfRnVsbENvbG9yX1JHQi5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"005656"}}]}},"version":"8.11.4","publishDate":"2026-03-05T21:21:00.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/c6ab5416-91b0-4d4f-9371-d7101a30f47b/RkFfRnVsbExvZ29fSG9yaXpfRnVsbENvbG9yX1JHQi5wbmc=","logoDark":"https://content.pstmn.io/095f1f08-ba60-4d34-b8e6-d357107b81e5/RkFfRnVsbExvZ29fSG9yaXpfV2hpdGVfUkdCLnBuZw=="}},"statusCode":200},"environments":[{"name":"INT","id":"7339d01d-891d-4ab0-9cbc-89b5efc93475","owner":"7075989","values":[{"key":"host","value":"https://api.us.int.sterlingcheck.app","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/821597f2e346e2cd87279687884179b76d9d414de12b17edfea3bf2ac90f0fbf","favicon":"https://res.cloudinary.com/postman/image/upload/v1773163808/team/516bf54cd0b68022526d06b3f9ad2bcb.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"INT","value":"7075989-7339d01d-891d-4ab0-9cbc-89b5efc93475"}],"canonicalUrl":"https://apidocs.sterlingcheck.app/view/metadata/TVRkZ7pA"}