{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Introduction to Trust products"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction-to-trust-products","__idx":0},"children":["Introduction to Trust products"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr Trust is a modern, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/Representational_state_transfer"},"children":["RESTful"]}," API-driven service designed to enhance trust and safety for your platform. The Checkr Trust API uses resource-oriented URLs, supports HTTPS for authentication and requests, and returns ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"http://www.json.org/"},"children":["JSON"]}," responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Checkr Trust API provides access to a rich set of data, including criminal records, traffic infractions, and registry checks. Once credentialed, you can start testing locally in minutes. For additional resources, please refer to our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.checkrtrust.com/resources/"},"children":["resource center"]},"."," ","This documentation aims to help you quickly utilize Checkr Trust’s services, offering context and technical guidance for working with the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-started","__idx":1},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following sections will guide you through the steps necessary to start running checks with the Checkr Trust API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#get-credentialed"},"children":["Get credentialed"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#authentication"},"children":["Authenticate with Checkr Trust"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#profiles"},"children":["Create a New Profile"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-new-check"},"children":["Create a New Check"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#parse-check-results"},"children":["Parse Check Results"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-new-driver-check"},"children":["Create a New Driver Check"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#parse-driver-check-results"},"children":["Parse Driver Check Results"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-new-identity-verification"},"children":["Create a New Identity Verification"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#parse-identity-verification-results"},"children":["Parse Identity Verification Results"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#regulated-criminal-reports"},"children":["Regulated Criminal Reports"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-new-regulated-criminal-report"},"children":["Create a New Regulated Criminal Report"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#parse-regulated-criminal-report-results"},"children":["Parse Regulated Criminal Report Results"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.getpostman.com/run-collection/38382010-a049bf07-c286-494a-bec8-990c7e2da1b2?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D38382010-a049bf07-c286-494a-bec8-990c7e2da1b2%26entityType%3Dcollection%26workspaceId%3D6cdee896-acb6-49a9-a227-a2aca6b3ad86#?env%5BCheckr%20Trust%5D=W3sia2V5IjoiYmFzZV91cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vYXBpLmNoZWNrcnRydXN0LmNvbS92MSIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiaHR0cHM6Ly9hcGkuY2hlY2tydHJ1c3QuY29tL3YxIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiJodHRwczovL2FwaS5jaGVja3J0cnVzdC5jb20vdjEiLCJzZXNzaW9uSW5kZXgiOjB9LHsia2V5IjoiY2xpZW50X2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4IjoxfSx7ImtleSI6ImNsaWVudF9zZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJhdXRoX3Rva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiYW55Iiwic2Vzc2lvblZhbHVlIjoiIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiIiLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5IjoiYXV0aF90b2tlbl9leHBpcmF0aW9uIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiYW55Iiwic2Vzc2lvblZhbHVlIjoiIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiIiLCJzZXNzaW9uSW5kZXgiOjR9XQ=="},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://run.pstmn.io/button.svg","alt":"Run In Postman"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-credentialed","__idx":2},"children":["Get Credentialed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you can request data from this API, you must first work with a Checkr Account Executive or Customer Success representative to set up and credential your account. You will receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," for the OAuth client-credentials flow described below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best practices for securing your API credentials:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not store your credentials in your codebase or commit them to version control. Instead, securely store them only in your production environment, such as in environment variables."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not expose credentials on the client side. All token exchange and API requests should be made from the server side, and only necessary data should be passed to the client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If credentials are compromised, contact Checkr immediately to revoke them. Checkr will expire the current credentials and your Account Executive or Customer Success Representative will issue new ones."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":3},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Protected endpoints require an OAuth 2.0 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer"]}," access token obtained with the"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client credentials"]}," grant (machine-to-machine). Checkr issues you a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," after you are credentialed — these are not end-user"," ","login credentials."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exchange them at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#operation/post-accounts-token"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /accounts/token"]}]}," ","for a JWT. Tokens typically expire in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["24 hours"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in: 86400"]},"); request a"," ","new token when the current one expires (this public token endpoint does not issue"," ","refresh tokens)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best practices:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," only in your server environment (never in"," ","client-side code or git)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat Pilot credentials like production secrets (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/accounts"},"children":["Accounts"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If credentials are compromised, contact Checkr immediately to rotate them."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oauth-20-client-credentials-overview","__idx":4},"children":["OAuth 2.0 client credentials (overview)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Role"},"children":["Role"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"In this API"},"children":["In this API"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your backend application"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization server"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checkr Trust / Auth0 (via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /accounts/token"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource server"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checkr Trust API (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/..."]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," the authorization-code (user login) flow. There is no browser redirect"," ","or resource-owner password grant on the public API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"obtaining-an-access-token","__idx":5},"children":["Obtaining an access token"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-1-access-token-request","__idx":6},"children":["Step 1: Access token request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /accounts/token"]}," with JSON ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},". Optional"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]}," must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}," when sent. Optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," is ignored;"," ","scopes come from your Auth0 client configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-request","__idx":7},"children":["Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl --location 'https://api.checkrtrust.com/v1/accounts/token' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"client_id\": \"YOUR_CLIENT_ID\",\n    \"client_secret\": \"YOUR_CLIENT_SECRET\",\n    \"grant_type\": \"client_credentials\"\n  }'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-2-access-token-response","__idx":8},"children":["Step 2: Access token response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 200"]}," with the token payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"eyJhb...(something long)...qJFlg\",\n  \"scope\": \"read:account create:account delete:account\",\n  \"expires_in\": 86400,\n  \"token_type\": \"Bearer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-the-access-token","__idx":9},"children":["Using the access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the token on every protected request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl --location 'https://api.checkrtrust.com/v1/checks' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Authorization: Bearer ACCESS_TOKEN' \\\n  --data '{\n    \"first_name\": \"John\",\n    \"last_name\": \"Smith\",\n    \"dob\": \"19880218\"\n  }'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Product endpoints (checks, profiles, and so on) authorize a valid Bearer token for"," ","your account plus an enabled product configuration. Some account/user management"," ","routes also require specific OAuth scopes on the token."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-handling","__idx":10},"children":["Error handling"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]}," — for example an unsupported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]},". Body uses this API's standard"," ","JSON:API-style ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}," — invalid client credentials or an Auth0 rejection. Body is Auth0's OAuth"," ","error object:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": \"access_denied\",\n  \"error_description\": \"Unauthorized\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]}," — the authentication provider returned an unexpected or unparsable"," ","response. Body uses this API's standard JSON:API-style ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":11},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our API uses webhooks to notify your application about asynchronous events, primarily when certain checks or verifications are completed. This allows you to receive results without needing to poll our API continuously."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration","__idx":12},"children":["Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure webhook endpoints in the dashboard under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration → Webhooks"]},", or with your Checkr Account Executive. The destination URL is set per product configuration, so an account running more than one webhook-enabled product must configure each product it wants webhooks for. Dashboard access requires an admin role; if you do not see the Webhooks tab, contact your Account Executive to set up or update the URL. You may optionally provide a dedicated shared secret for signature verification; if you do not, we sign webhooks with your account's OAuth ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-usage-driver-checks--document-verification","__idx":13},"children":["Required Usage: Driver Checks & Document Verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Receiving results for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_checks"]}," (both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_license_status"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["motor_vehicle_report"]},") ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["requires"]}," a configured webhook endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The results are delivered asynchronously via a webhook payload once the check/verification is complete. See the specific event schemas defined under the callbacks for the respective POST operations:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /driver_checks"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver-license-status-completed-event-body"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["motor-vehicle-report-completed-event-body"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"adverse-action-webhooks","__idx":14},"children":["Adverse Action Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three customer webhooks are delivered across the adverse-action lifecycle. All three events share one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action_webhooks"]}," configuration, resolved per check from the product configuration of the check the adverse action belongs to (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instant_criminal_regulated"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["county_criminal_regulated"]},"):"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Schema"},"children":["Schema"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre_adverse_action.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subject accepts a pre-adverse action (transitions to the terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]}," state). PreAdverseAction only."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre-adverse-action-completed-event-body"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.dispute_filed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subject files a dispute against a (pre-)adverse action. Fires for both pre-adverse and final adverse actions."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse-action-dispute-filed-event-body"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action.dispute_resolved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Admin resolves a filed dispute (with or without changes). Fires for both pre-adverse and final adverse actions."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse-action-dispute-resolved-event-body"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration:"]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action_webhooks.destination_url"]}," (and optionally ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action_webhooks.signature_key"]},") on each adverse-action-enabled product configuration whose checks should emit webhooks. The settings are resolved per check from that check's own product configuration — they are not a single shared/global account setting, so an account running both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instant_criminal_regulated"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["county_criminal_regulated"]}," must configure each product it wants webhooks for. Contact your Checkr Account Executive to configure these settings. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature_key"]}," is not set, the account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," is used as the signing key. The same destination and signing key are used for all three events. Optionally set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action_webhooks.dispute_notifications_email"]}," to also send dispute-resolution notices to a customer contact; when unset, only the subject (consumer) notice is sent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payloads:"]}," All three event bodies are intentionally minimal. The dispute events include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.adverse_action_type"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre_adverse_action"]}," | ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action"]},") to disambiguate the lifecycle stage and select the GET endpoint for full details:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre_adverse_action"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /regulated/pre_adverse_actions/{pre_adverse_action_id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse_action"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /regulated/adverse_actions/{adverse_action_id}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre-adverse-action-completed-event-body"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse-action-dispute-filed-event-body"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adverse-action-dispute-resolved-event-body"]}," schemas in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#operation/post-regulated-pre-adverse-action"},"children":["Create a pre-adverse action"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#operation/post-regulated-adverse-action"},"children":["Create an adverse action"]}," callbacks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payload-signing--verification-hmac-sha256","__idx":15},"children":["Payload Signing & Verification (HMAC-SHA256)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook payload is signed with HMAC-SHA256 so you can verify integrity and authenticity. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Signing is always applied"]}," — it is not optional. What ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["is"]}," optional is configuring a dedicated signing key; by default we use your account's OAuth ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," (the same secret used for the client-credentials token flow)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it Works:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["We generate a signature for each webhook event payload using a shared secret."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["By default, that secret is your account's OAuth ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally, you can configure a dedicated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature_key"]}," on the product configuration (via your Account Executive). When set, that key is used instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},". A dedicated key is recommended so a compromised webhook endpoint does not expose your OAuth credential."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The signature is calculated using the HMAC-SHA256 algorithm on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw JSON payload"]}," of the webhook request body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The resulting signature (as a hexadecimal string) is included in the webhook request's HTTP headers, under the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Checkr-Signature"]}," header with the value ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256={signature}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verifying the Signature (Recommended):"]}," ","You should verify this signature on your end to confirm that the payload was sent by Checkr and hasn't been tampered with."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verification Steps:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extract the signature from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Checkr-Signature"]}," (or the specific header name provided to you) header of the incoming request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw request body"]},". It is crucial ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["not"]}," to parse and re-serialize the JSON before verification, as minor changes (like whitespace or key order) can invalidate the signature."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compute the HMAC-SHA256 hash of the raw payload string using your signing key (your dedicated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature_key"]},", or your OAuth ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," if none is configured)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Convert the computed hash to its hexadecimal representation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare the signature extracted from the header with your computed signature. Use a timing-safe comparison function provided by your language/framework to prevent timing attacks."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Code Examples for Verification:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Ruby:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'openssl'\n# For secure_compare, typically available in Rails/ActiveSupport\nrequire 'active_support/security_utils'\n\n# Assuming 'request' is your HTTP request object\n# and 'SIGNATURE_KEY' is your dedicated signing key, or your OAuth\n# client_secret if no dedicated signature_key is configured\nprovided_signature = request.headers['X-Checkr-Signature']&.split('=')&.last\nraise 'signature missing' unless provided_signature\n\n# Ensure you get the raw body, not parsed JSON\npayload_body = request.raw_post\n\nexpected_signature = OpenSSL::HMAC.hexdigest('SHA256', SIGNATURE_KEY, payload_body)\n\n# Use secure_compare for timing-attack resistance\nis_valid = ActiveSupport::SecurityUtils.secure_compare(provided_signature, expected_signature)\n\nif is_valid\n  # Signature is valid, process the webhook payload\n  puts \"Webhook signature verified.\"\nelse\n  # Signature is invalid, reject the request\n  puts \"Webhook signature verification failed.\"\n  # Return an appropriate error response (e.g., 401 Unauthorized)\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delivery-attempts--reliability","__idx":16},"children":["Delivery Attempts & Reliability"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our system will attempt to deliver webhook events to your configured endpoint."," ","If your endpoint returns a non-2xx status code (e.g., 4xx, 5xx) or fails to respond within a reasonable timeout, we will retry sending that event. We retry up to 25 times with exponential time backoff (e.g. after 15 seconds, 16 seconds, 30 seconds, 90 seconds, etc) for a total period of around 20 days."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is crucial that your endpoint:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Responds quickly with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," status upon successful receipt of the request (ideally before performing complex processing)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is designed to handle potential duplicate events (e.g., due to network issues or retries)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handles the signature verification process robustly."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"profiles","__idx":17},"children":["Profiles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Profiles represent a set of Personally Identifiable Information (PII) for a person who will be checked."," ","Profiles can be updated with the latest information for a person and be referenced to generate checks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"name-validation","__idx":18},"children":["Name validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr attempts to prevent malformed names (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["12345"]},") from being submitted. This applies"," ","anywhere a name is accepted: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["full_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["middle_name"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]},". A request that"," ","contains a name determined to be malformed is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_error"]}," ","whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.pointer"]}," identifies the offending field (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/first_name"]},"). No profile is created or"," ","updated and no check is run."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checks","__idx":19},"children":["Checks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks provide the resulting information relevant to the requested check for a set of PII."," ","The response will include the check type and results."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-new-check","__idx":20},"children":["Create a New Check"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates a new check, immediately returning the results."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required attributes for a check resource vary depending on its intended use."," ","Each check requires a minimum set of attributes."," ","You can pass through the minimum set of PII or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," to reference the profile’s PII—not both."," ","Combining ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," with inline PII or address fields returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."," ","If the PII is insufficient for a check, a validation error will return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields required to generate an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Instant Criminal Check"]}," include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Although dob (date of birth) is encouraged, it is not required."," ","Searches without dob will give back results that are matched by name only, which may be false positives."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parse-check-results","__idx":21},"children":["Parse Check Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Synchronous responses for a check and GET requests for a check both contain the same information about the results of the check."," ","A completed check with empty results indicates that there are no items on the person’s record for review."," ","Results that are populated indicate items on the check that may require review."," ","Results may not be used to determine eligibility for credit, insurance, employment, or any other purpose regulated under the FCRA."," ","Additionally, Checkr does not make any policy decisions on behalf of its customers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"driver-checks","__idx":22},"children":["Driver Checks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Driver checks provide the resulting information relevant to the requested driver license."," ","The response will include the driver check type and results."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-new-driver-check","__idx":23},"children":["Create a New Driver Check"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates a new Driver Check, returning the results asynchronously, using a pre-defined webhook."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required attributes for a driver check vary depending on its intended use."," ","You can pass through the minimum set of PII or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," to reference the profile’s PII—not both."," ","Combining ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," with inline PII or address fields returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."," ","If the PII is insufficient for a driver check, a validation error will return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields required to generate a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Driver Check"]}," include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dob"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_license_number"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driver_license_state"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parse-driver-check-results","__idx":24},"children":["Parse Driver Check Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Asynchronous responses for a Driver Check and GET requests for a Driver Check both contain the same information about the results."," ","You must expose a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#webhooks"},"children":["Webhook endpoint"]}," on your end to receive Driver Check completion events."," ","Configure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive."," ","Additionally, Checkr does not make any policy decisions on behalf of its customers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-verifications","__idx":25},"children":["Identity Verifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity Verifications provide the resulting information relevant to the requested verification for a set of PII."," ","The response will include the IDV type and results."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-new-identity-verification","__idx":26},"children":["Create a New Identity Verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates a new Identity Verification check."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required attributes for an Identity Verification resource vary depending on its intended use."," ","You can pass through the minimum set of PII or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," to reference the profile’s PII—not both."," ","Combining ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," with inline PII or address fields returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_id"]}," may accompany ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]},")."," ","If the PII is insufficient for a verification, a validation error will return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields required to generate an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Identity Verification"]}," include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idv_type"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["any of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email, phone, dob"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parse-identity-verification-results","__idx":27},"children":["Parse Identity Verification Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity Verifications of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idv_type"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pii_validation"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["personal_identity_records"]}," use synchronous responses. Responses for POST and GET requests for an Identity Verification both contain the same information about the results. A completed Identity Verification will provide match scores for each attribute provided (first name, last name, email, phone, etc); and an overall match score."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity Verifications of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idv_type"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_verification"]}," use asynchronous responses. The POST request contains an initial payload with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collection_link"]}," to provide to your end user; they use the web application at that link on a mobile device to provide the documents we will verify. You must expose a Webhook endpoint to receive the completed document verification, which contains the same information and results as a GET request once the request is completed. Configure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additionally, Checkr does not make any policy decisions on behalf of its customers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"regulated-criminal-reports","__idx":28},"children":["Regulated Criminal Reports"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Regulated Criminal Reports provide asynchronous criminal record check results with legal annotation. Unlike instant criminal checks, results are not returned in the HTTP response. Instead, the API accepts your request, returns a report ID and status, and delivers the full results via webhook once processing is complete."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This product is designed for Fair Credit Reporting Act (FCRA) regulated use cases where legal annotation of criminal records is required. Results include checks at the record, case, and charge levels indicating whether items should be included, investigated, or removed based on applicable legal rules for the specified jurisdictions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"data-flow","__idx":29},"children":["Data Flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a report"]}," — Submit a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /regulated/criminal_reports"]}," request with the subject's PII (or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]},") along with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter_context"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissible_purpose"]},". The API responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," and a JSON body containing the report ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (initially ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receive results via webhook"]}," — Once processing is complete, the full report (including criminal records, cases, charges, and legal annotation checks) is delivered to your configured webhook endpoint. You must have a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#webhooks"},"children":["webhook endpoint"]}," configured to receive these results."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retrieve results on demand"]}," — You can also retrieve a report at any time using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /regulated/criminal_reports/{id}"]},". Once the report is complete, the response includes the full results. You can list all reports for your account using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /regulated/criminal_reports"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-new-regulated-criminal-report","__idx":30},"children":["Create a New Regulated Criminal Report"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A regulated criminal report requires the following fields when submitting PII directly:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dob"]}," (date of birth in YYYYMMDD format)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter_context"]}," with at least a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate_jurisdiction"]}," containing a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissible_purpose"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Employment"]},")"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, pass a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," (without inline PII) along with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter_context"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissible_purpose"]},". Combining ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]}," with inline PII or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addresses"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_id"]}," may be sent with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile_id"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-request-1","__idx":31},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl --location 'https://api.checkrtrust.com/v1/regulated/criminal_reports' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ACCESS_TOKEN' \\\n--data '{\n    \"first_name\": \"John\",\n    \"last_name\": \"Smith\",\n    \"dob\": \"19900101\",\n    \"filter_context\": {\n        \"candidate_jurisdiction\": {\n            \"state\": \"CA\"\n        },\n        \"decider_jurisdiction\": {\n            \"state\": \"NY\"\n        }\n    },\n    \"permissible_purpose\": \"Employment\"\n}'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-response-202-accepted","__idx":32},"children":["Example Response (202 Accepted)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"{\n    \"id\": \"2b8313e8-4efd-45a1-b578-952b8313e890\",\n    \"status\": \"pending\"\n}\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parse-regulated-criminal-report-results","__idx":33},"children":["Parse Regulated Criminal Report Results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the report is complete, the full results are available via the webhook payload and through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /regulated/criminal_reports/{id}"]},". The response includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]}," — The report status (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}]}," — An array of criminal records found. Each record contains:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["person"]}]}," — Identifying information for the matched individual (name, DOB, addresses, etc.)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cases"]}]}," — Court cases associated with the record, each containing ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["charges"]}]}," with offense details, sentences, and dispositions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]}," — The data source where the record was found."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checks"]}]}," — Legal annotation check results at the record, case, and charge levels. Each check includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["investigate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modified"]},"), a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rule_id"]},", and a human-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," of the legal rule applied."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["check_type"]}]}," — Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regulated_criminal_report"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["run_notes"]}]}," — Any informational notes about how input was parsed or about the results."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A completed report with empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}," indicates that no criminal records were found for the subject."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Results may only be used for purposes permitted under the Fair Credit Reporting Act (FCRA), consistent with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissible_purpose"]}," provided at the time of the request."]}]},"headings":[{"value":"Introduction to Trust products","id":"introduction-to-trust-products","depth":2},{"value":"Getting Started","id":"getting-started","depth":2},{"value":"Get Credentialed","id":"get-credentialed","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"OAuth 2.0 client credentials (overview)","id":"oauth-20-client-credentials-overview","depth":3},{"value":"Obtaining an access token","id":"obtaining-an-access-token","depth":3},{"value":"Step 1: Access token request","id":"step-1-access-token-request","depth":4},{"value":"Example request","id":"example-request","depth":4},{"value":"Step 2: Access token response","id":"step-2-access-token-response","depth":4},{"value":"Using the access token","id":"using-the-access-token","depth":3},{"value":"Error handling","id":"error-handling","depth":3},{"value":"Webhooks","id":"webhooks","depth":2},{"value":"Configuration","id":"configuration","depth":3},{"value":"Required Usage: Driver Checks & Document Verification","id":"required-usage-driver-checks--document-verification","depth":3},{"value":"Adverse Action Webhooks","id":"adverse-action-webhooks","depth":3},{"value":"Payload Signing & Verification (HMAC-SHA256)","id":"payload-signing--verification-hmac-sha256","depth":3},{"value":"Delivery Attempts & Reliability","id":"delivery-attempts--reliability","depth":3},{"value":"Profiles","id":"profiles","depth":2},{"value":"Name validation","id":"name-validation","depth":3},{"value":"Checks","id":"checks","depth":2},{"value":"Create a New Check","id":"create-a-new-check","depth":3},{"value":"Parse Check Results","id":"parse-check-results","depth":3},{"value":"Driver Checks","id":"driver-checks","depth":2},{"value":"Create a New Driver Check","id":"create-a-new-driver-check","depth":3},{"value":"Parse Driver Check Results","id":"parse-driver-check-results","depth":3},{"value":"Identity Verifications","id":"identity-verifications","depth":2},{"value":"Create a New Identity Verification","id":"create-a-new-identity-verification","depth":3},{"value":"Parse Identity Verification Results","id":"parse-identity-verification-results","depth":3},{"value":"Regulated Criminal Reports","id":"regulated-criminal-reports","depth":2},{"value":"Data Flow","id":"data-flow","depth":3},{"value":"Create a New Regulated Criminal Report","id":"create-a-new-regulated-criminal-report","depth":3},{"value":"Example Request","id":"example-request-1","depth":4},{"value":"Example Response (202 Accepted)","id":"example-response-202-accepted","depth":4},{"value":"Parse Regulated Criminal Report Results","id":"parse-regulated-criminal-report-results","depth":3}],"frontmatter":{"seo":{"title":"Introduction to Trust products"}},"lastModified":"2026-10-07T20:00:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}