{ "openapi": "3.1.0", "info": { "title": "Checkr Trust API", "version": "1.0", "summary": "Checkr Trust is a modern, 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 JSON responses.\n\nThe 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.\n\n## Intended Use Cases\n\nImportant: Checkr Trust is not a “consumer reporting agency” or otherwise a producer of “consumer reports,” as those terms are defined in the Fair Credit Reporting Act (“FCRA”). Checkr Trust data must not be accessed, obtained, disclosed, or otherwise used to make any decisions related to credit, insurance, employment, or any other purposes described in 15 U.S.C. § 1681b of FCRA\n", "contact": { "name": "API Development Team", "email": "checkr-trust@checkr.com", "url": "https://checkrtrust.com" }, "license": { "name": "Proprietary", "url": "https://checkrtrust.com" } }, "servers": [ { "url": "https://api.checkrtrust.com/v1", "description": "Checkr Trust API" } ], "security": [ { "get-bearer-token-using-oauth2": [] } ], "x-tagGroups": [ { "name": "Resources", "tags": [ "Accounts", "Bulk Uploads", "Instant Criminal Checks", "Profile Criminal Checks", "Criminal Checks", "County Checks", "Driver Checks", "Identity Verifications", "Profiles", "Regulated Adverse Action", "Regulated Instant Criminal Checks", "Regulated County Checks", "Regulated Criminal Reports", "Regulated Eviction Checks", "Test Scenarios" ] } ], "tags": [ { "name": "Accounts", "description": "Account credentialing and OAuth 2.0 **client credentials** token issuance\n([`POST /accounts/token`](#operation/post-accounts-token)). See\n[Authentication](./index.md#authentication) for the end-to-end flow.\nAccount creation and environment setup are done with a Checkr Account\nExecutive.\n" }, { "name": "Bulk Uploads", "description": "Bulk Uploads accept a CSV of subjects and run supported check products in batch.\nInstant Criminal products complete each row synchronously. County Criminal products\nsubmit asynchronously and finalize result files once every row is terminal.\nRegulated products require a FCRA `permissible_purpose` in upload settings.\n" }, { "name": "County Checks", "description": "County Checks provide county-level criminal background check results for a specific jurisdiction. Results are retrieved from county court records and can be cancelled while in pending status." }, { "name": "Criminal Checks", "description": "Criminal Checks provide criminal record check results asynchronously. Results become available via GET once the check completes; when a webhook is configured, they are also delivered to that endpoint." }, { "name": "Driver Checks", "description": "Driver Checks provide the resulting information relevant to the requested driver license. The response will include the driver check type and results." }, { "name": "Identity Verifications", "description": "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." }, { "name": "Instant Criminal Checks", "description": "Instant Criminal Checks provide the resulting information relevant to the requested check for a set of PII. Checks include the check type and **results**.\n\n**Results and confidence scoring:** Each criminal **case** inside `results[].cases[]` may include `identity_match_confidence_level` when identity matching applies. That field summarizes how well the case matches the subject you searched (high, medium, low, or special values such as unknown or insufficient_information). See the `case` schema in the checks component for full semantics.\n\nEach **record** may separately include `record_match_confidence_level`, summarizing how strongly that whole record aligns with the identity it was matched to (high, medium, or low). The two are measured independently and are not comparable to each other. See the `record` schema in the checks component.\n" }, { "name": "Profile Criminal Checks", "description": "Profile Criminal Checks provide a people-data-graph-native, profile-centric alternative to\nInstant Criminal Checks. Instead of a flat records array, `results` is an array of matched\nidentities (profiles) -- each with a conservative identity summary and its own nested\ncriminal records -- so you can review which identity matched before drilling into its records.\n\n{% partial file=\"/_partials/beta-provisional-notice.md\" /%}\n" }, { "name": "Profiles", "description": "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." }, { "name": "Regulated Adverse Action", "description": "Regulated Adverse Action provides two separate endpoints for the FCRA adverse action flow:\nPre-Adverse Action and Adverse Action.\n\nPre-Adverse Action notifies the subject of a pending adverse decision, delivers a copy of\nthe report, and provides required FCRA disclosures — giving them an opportunity to dispute\nbefore a final decision is made. This step is optional but must precede a final adverse\naction if used.\n\nAdverse Action finalizes the adverse decision and delivers the required notice to the subject.\nIt may be submitted with or without a prior pre-adverse action.\n" }, { "name": "Regulated County Checks", "description": "Regulated County Checks provide county-level or statewide criminal background check results for a specific jurisdiction. `county_fips_code` is required. Provide a 5-digit FIPS code for a county-level search, or the literal `statewide` for a state-level search. Results include checks at the record, case, and charge levels indicating compliance with applicable legal rules. A permissible purpose is required for FCRA compliance." }, { "name": "Regulated Criminal Reports", "description": "Regulated Criminal Reports provide asynchronous criminal record check results with legal annotation. Results are delivered via webhook once processing is complete. A permissible purpose is required for Fair Credit Reporting Act (FCRA) compliance." }, { "name": "Regulated Eviction Checks", "description": "Regulated Eviction Checks surface eviction court records. Results are returned synchronously and include case filing details, plaintiff information, and judgement data." }, { "name": "Regulated Instant Criminal Checks", "description": "Regulated Instant Criminal Checks provide instant criminal record check results with legal annotation. Results include checks at the record, case, and charge levels indicating compliance with applicable legal rules. A permissible purpose is required for FCRA compliance." }, { "name": "Test Scenarios", "description": "The deterministic mock scenarios a test account can exercise, with the exact inputs that\ntrigger each one. This is the source of truth for scenario inputs; the\n[Test Accounts](./test-accounts.md) guide covers the surrounding behavior but does not\nenumerate scenarios. Accounts outside the Test environment receive an empty list.\n" } ], "paths": { "/accounts/token": { "post": { "summary": "Create token", "description": "Exchange your `client_id` and `client_secret` for a Bearer\naccess token (OAuth 2.0 **client credentials**).\n\n- `grant_type` is optional; when sent it must be `client_credentials`.\n Any other value returns `400`.\n- `scope` in the request body is optional and ignored; scopes on the\n token come from your Auth0 client configuration.\n- Successful Auth0 responses are returned as **`200`** with the standard\n token fields (`access_token`, `token_type`, `expires_in`, `scope`).\n- Invalid credentials or Auth0 rejections are passed through (typically\n **`401`**) with Auth0's OAuth error body.\n- If the authentication provider returns an unexpected or unparsable\n response, a **`500`** is returned with the standard API error array.\n\nStep-by-step guide: [Authentication](./index.md#authentication).\n", "tags": [ "Accounts" ], "requestBody": { "$ref": "#/components/requestBodies/post-token-request-body" }, "responses": { "200": { "$ref": "#/components/responses/post-token-response-body" }, "400": { "description": "Bad request — for example `grant_type` was provided and is not\n`client_credentials`. Body uses the standard API error array.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "$ref": "#/components/responses/post-token-unauthorized-response-body" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-accounts-token", "security": [] } }, "/bulk_uploads": { "get": { "summary": "List bulk uploads", "description": "List bulk uploads for the authenticated account, newest first.\n", "tags": [ "Bulk Uploads" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/bulk_upload" } } } } }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-bulk-uploads", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create bulk upload", "description": "Upload a CSV of subjects and start asynchronous validation for a supported\ncheck product.\n\nSupported `product_name` values:\n- `instant_criminal`\n- `instant_criminal_regulated` (requires `settings.permissible_purpose`; per-row `dob`)\n- `county_criminal` (CSV rows must include `state`, `county_fips_code`, and `dob`)\n- `county_criminal_regulated` (same county CSV columns; plus `settings.permissible_purpose`; per-row `dob`)\n\nCSV column requirements, header aliases, and example rows for each product are\ndocumented on the request body schema below.\n\nOn success the upload is created in `submitted` / moves through validation.\nInstant products complete each row when the check factory returns. County\nproducts submit provider searches asynchronously; the upload stays in\n`processing` until every row is terminal, then result files are generated.\n\nCounty rows are also subject to the same pilot jurisdiction blocks and\nfulfillment submission caps as single county checks.\n", "tags": [ "Bulk Uploads" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/bulk_upload_create_request" }, "encoding": { "original_file": { "contentType": "text/csv, application/csv, text/plain, application/vnd.ms-excel" }, "settings": { "style": "deepObject", "explode": true } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_upload" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-bulk-uploads", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/bulk_uploads/{bulk_upload_id}": { "get": { "summary": "Get bulk upload", "description": "Get a single bulk upload by id.", "tags": [ "Bulk Uploads" ], "parameters": [ { "$ref": "#/components/parameters/bulk_upload_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_upload" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-bulk-uploads-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/bulk_uploads/{bulk_upload_id}/original": { "get": { "summary": "Download original CSV", "description": "Download the original uploaded CSV file.", "tags": [ "Bulk Uploads" ], "parameters": [ { "$ref": "#/components/parameters/bulk_upload_id" } ], "responses": { "200": { "description": "Original CSV attachment", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-bulk-uploads-id-original", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/bulk_uploads/{bulk_upload_id}/results": { "get": { "summary": "Download result file", "description": "Download generated results. Default `format=csv` returns the summary CSV.\nPass `format=xlsx` for the detailed spreadsheet.\n", "tags": [ "Bulk Uploads" ], "parameters": [ { "$ref": "#/components/parameters/bulk_upload_id" }, { "name": "format", "in": "query", "required": false, "description": "Result file format.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ], "default": "csv" } } ], "responses": { "200": { "description": "Result file attachment", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-bulk-uploads-id-results", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/bulk_uploads/{bulk_upload_id}/force_run": { "post": { "summary": "Force-run a validated bulk upload", "description": "Enqueue processing for a bulk upload in `validated` or `invalid_input`\nwhen at least one runnable row remains. Returns `201 Created` when the\njob is queued (this endpoint predates the `202` convention used by\n`regenerate_results`). Poll `GET /v1/bulk_uploads/{bulk_upload_id}` for\nstate transitions — do not poll this POST endpoint.\n", "tags": [ "Bulk Uploads" ], "parameters": [ { "$ref": "#/components/parameters/bulk_upload_id" } ], "responses": { "201": { "description": "Enqueued (returns 201 for backward compatibility)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Bulk upload enqueued for processing" } }, "required": [ "message" ] } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-bulk-uploads-id-force-run", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/bulk_uploads/{bulk_upload_id}/regenerate_results": { "post": { "summary": "Regenerate result files", "description": "Enqueue asynchronous regeneration of the summary CSV and detailed XLSX result\nfiles for an existing bulk upload. This does not re-run checks — it only rebuilds\nexport files from already-stored row outcomes.\n\n**Do not poll this endpoint.** Each POST enqueues a separate background job; there\nis no idempotency or deduplication of in-flight regeneration work. Call once after\nprocessing completes, then poll `GET /v1/bulk_uploads/{bulk_upload_id}` (and\ndownload `result_file` / `detailed_result_file` when attached) for completion.\n", "tags": [ "Bulk Uploads" ], "parameters": [ { "$ref": "#/components/parameters/bulk_upload_id" } ], "responses": { "202": { "description": "Regeneration job accepted (enqueued)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Result file regeneration enqueued" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-bulk-uploads-id-regenerate-results", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/checks": { "get": { "summary": "Get checks", "description": "Get a set of checks", "tags": [ "Instant Criminal Checks" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_check_index" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/check" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create check", "description": "Create a new check.\n\n{% partial file=\"/_partials/profile-id-pii-mutual-exclusivity.md\" /%}\n", "tags": [ "Instant Criminal Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_check_show" } ], "requestBody": { "$ref": "#/components/requestBodies/post-check-request-body" }, "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/checks/{check_id}": { "get": { "summary": "Get check", "description": "Get a single check with a given id", "tags": [ "Instant Criminal Checks" ], "parameters": [ { "description": "the uuid identifying the check", "$ref": "#/components/parameters/check_id" }, { "$ref": "#/components/parameters/include_check_show" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/checks/{check_id}/report": { "get": { "summary": "Download check report (PDF)", "description": "Download a PDF report for a single instant criminal check. The file is returned as an attachment\n(`Content-Disposition: attachment`) with a suggested filename of `{first_name} {last_name} - check results.pdf`.\nWhen first or last name is unavailable, `{check_id} - check results.pdf` is used instead.\n\nThe PDF reflects the same result shaping as the JSON check resource.\n\n**Availability:** Returns `422 Unprocessable Content` with a JSON body when the check has not finished\nand results are not yet available (no completed results).\n", "tags": [ "Instant Criminal Checks" ], "parameters": [ { "description": "the uuid identifying the check", "$ref": "#/components/parameters/check_id" } ], "responses": { "200": { "description": "PDF document", "headers": { "Content-Disposition": { "description": "Attachment with suggested filename `{first_name} {last_name} - check results.pdf`.\n", "schema": { "type": "string", "example": "attachment; filename=\"Jane Doe - check results.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "description": "The check was not found, or it does not belong to the authenticated account.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Report not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Results are not yet available for this check (the check has not completed).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Results are not yet available for this check" } }, "required": [ "error" ] } } } }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-check-report-pdf", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/driver_checks": { "get": { "summary": "Get driver checks", "description": "Get a set of previously created driver checks", "tags": [ "Driver Checks" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/driver_check_driver_license_status" }, { "$ref": "#/components/schemas/driver_check_motor_vehicle_report" } ] } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-driver-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create driver check", "description": "Create a new driver check.\n\n{% partial file=\"/_partials/profile-id-pii-mutual-exclusivity-driver-checks.md\" /%}\n\n{% partial file=\"/_partials/driver-check-inline-address-persistence.md\" /%}\n\nFor `motor_vehicle_report` checks in Washington (`WA`), only DPPA purposes `employment` and `insurance` are supported.\nIf your account is configured with a different DPPA purpose, requests for `motor_vehicle_report` checks in `WA` will be rejected.\nThis restriction does not apply to `driver_license_status` checks.\n", "tags": [ "Driver Checks" ], "parameters": [ { "$ref": "#/components/parameters/unmask_ssn" } ], "requestBody": { "$ref": "#/components/requestBodies/post-driver-check-request-body" }, "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/driver_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "409": { "description": "Conflict — the upstream driver-check provider rejected the order (for example, a\nconflicting or duplicate request). Inspect the error payload for provider details.\nThe check is not created; correct the request or retry after resolving the conflict.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "callbacks": { "onSearchCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Driver Check Completion Webhook", "description": "Callback (webhook) triggered when the driver check search is finished. \n\nDriver check clients must configure this webhook URL, either in the dashboard under Configuration or with their Checkr Account Executive. \n\nThe payload contains the results for either `driver_license_status` or `motor_vehicle_report` checks, depending on what was initiated. See the schemas below for details.\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on signature verification.\n", "requestBody": { "description": "Payload containing the driver check results", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/driver-license-status-completed-event-body" }, { "$ref": "#/components/schemas/motor-vehicle-report-completed-event-body" } ] } } } }, "responses": { "2xx": { "description": "Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.\nWe treat any 2xx as success and will not retry the POST.\n" }, "4xx": { "description": "HTTP status codes in the 4xx range indicate client errors (e.g., 400 Bad Request, 401 Unauthorized).\nReturning a 4xx status may result in retries depending on the specific status code.\n" } } } } } }, "operationId": "post-driver-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/driver_checks/{driver_check_id}": { "get": { "summary": "Get driver check", "description": "Get a previously created driver check with a given id", "tags": [ "Driver Checks" ], "parameters": [ { "description": "the uuid identifying the driver check", "$ref": "#/components/parameters/driver_check_id" }, { "$ref": "#/components/parameters/include_profile_only" }, { "$ref": "#/components/parameters/unmask_ssn" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/driver_check_driver_license_status" }, { "$ref": "#/components/schemas/driver_check_motor_vehicle_report" } ] } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-driver-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/identity_verifications": { "get": { "summary": "Get identity verifications", "description": "Get a set of identity verifications", "tags": [ "Identity Verifications" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_profile_only" }, { "$ref": "#/components/parameters/unmask_ssn_identity_verification" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/identity_verification" } } } } }, "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-identity-verifications", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create identity verification", "description": "Create a new identity verification.\n\n{% partial file=\"/_partials/profile-id-pii-mutual-exclusivity-reference-id-allowed.md\" /%}\n", "tags": [ "Identity Verifications" ], "requestBody": { "$ref": "#/components/requestBodies/post-identity-verification-request-body" }, "parameters": [ { "$ref": "#/components/parameters/include_profile_only" }, { "$ref": "#/components/parameters/unmask_ssn_identity_verification" } ], "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/identity_verification_post_response" } } } }, "204": { "$ref": "#/components/responses/reverse-phone-no-info" }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-identity-verifications", "security": [ { "get-bearer-token-using-oauth2": [] } ], "callbacks": { "onDocumentVerificationCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Callback (webhook) triggered when document verification is completed.", "description": "This callback is invoked when an identity verification of type 'document_verification' reaches a final state (complete, failed, etc.). The URL is pre-configured for the client account.", "requestBody": { "description": "Payload containing the completed document verification details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document-verification-completed-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.\nWe treat any 2xx as success and will not retry the POST.\n" }, "4xx": { "description": "If your webhook handler returns a 4xx or 5xx status, we will retry the POST a set number of times (with exponential backoff).\n" } } } } } } } }, "/identity_verifications/{identity_verification_id}": { "get": { "summary": "Get identity verification", "description": "Get a single identity verification with a given id", "tags": [ "Identity Verifications" ], "parameters": [ { "description": "the uuid identifying the identity verification", "$ref": "#/components/parameters/identity_verification_id" }, { "$ref": "#/components/parameters/include_profile_only" }, { "$ref": "#/components/parameters/unmask_ssn_identity_verification" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/identity_verification" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-identity-verification-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/identity_verifications/{identity_verification_id}/files": { "get": { "summary": "Download collected document images", "description": "(Document Verification only) Download a ZIP of collected images for the specified identity verification. \nThe ZIP contains the following files:\n- Doc_Selfie_1_blob.jpg - the selfie image\n- documentbackDoc_Back_1_blob.jpg - the document back image\n- documentfrontDoc_Front_1_blob.jpg - the document front image\n", "tags": [ "Identity Verifications" ], "parameters": [ { "description": "the uuid identifying the identity verification", "$ref": "#/components/parameters/identity_verification_id" } ], "responses": { "200": { "description": "ZIP file", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "422": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } }, "operationId": "get-identity-verification-files", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/profiles": { "get": { "summary": "Get profiles", "description": "Get a set of profiles", "tags": [ "Profiles" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/profile" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-profiles", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create profile", "description": "Create a new profile with personally identifiable information (PII).\n\nThe profile can include various identity fields (SSN, email, phone) which are used for identity verification\nand record matching in check products. The more identity fields provided, the better\nthe matching and verification capabilities will be.\n", "tags": [ "Profiles" ], "requestBody": { "$ref": "#/components/requestBodies/post-profile-request-body" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profile" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-profiles", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/profiles/{profile_id}": { "get": { "summary": "Get profile", "description": "Get a single profile with a given id", "tags": [ "Profiles" ], "parameters": [ { "description": "the uuid identifying the profile", "$ref": "#/components/parameters/profile_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profile" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-profile-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/checks": { "get": { "summary": "Get regulated checks", "description": "Get a set of regulated instant criminal checks for the authenticated account.", "tags": [ "Regulated Instant Criminal Checks" ], "parameters": [ { "description": "Limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "Skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_regulated_index" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/regulated_check" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create regulated check", "description": "Create a new regulated criminal background check with legal annotation.\n\nThis endpoint performs an instant criminal check and applies legal rules based on\nthe provided jurisdiction context. Results include legal annotation checks at the\nrecord, case, and charge levels indicating whether items should be included,\ninvestigated, or removed based on applicable regulations.\n\nA permissible purpose must be provided to comply with FCRA requirements.\n\n{% partial file=\"/_partials/profile-id-pii-regulated-checks.md\" /%}\n", "tags": [ "Regulated Instant Criminal Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_regulated_show" } ], "requestBody": { "$ref": "#/components/requestBodies/post-regulated-check-request-body" }, "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-regulated-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/checks/{check_id}": { "get": { "summary": "Get regulated check", "description": "Get a single regulated check with a given id.", "tags": [ "Regulated Instant Criminal Checks" ], "parameters": [ { "description": "The uuid identifying the check", "$ref": "#/components/parameters/check_id" }, { "$ref": "#/components/parameters/include_regulated_show" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/criminal_reports": { "get": { "summary": "Get regulated criminal reports", "description": "Get a set of regulated criminal reports for the authenticated account.", "tags": [ "Regulated Criminal Reports" ], "parameters": [ { "description": "Limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "Skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/regulated_criminal_report" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-criminal-reports", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create regulated criminal report", "description": "Create a new regulated criminal report with legal annotation.\n\nThis endpoint creates an asynchronous criminal report that applies legal rules based on\nthe provided jurisdiction context. Results include legal annotation checks at the\nrecord, case, and charge levels indicating whether items should be included,\ninvestigated, or removed based on applicable regulations.\n\nA permissible purpose must be provided to comply with Fair Credit Reporting Act (FCRA) requirements.\n\n{% partial file=\"/_partials/profile-id-pii-regulated-criminal-reports.md\" /%}\n\n**Important Notes:**\n- Results are NOT returned in the HTTP response (returns 202 Accepted)\n- Full results are delivered asynchronously via webhook once processing is complete\n", "tags": [ "Regulated Criminal Reports" ], "requestBody": { "$ref": "#/components/requestBodies/post-regulated-criminal-report-request-body" }, "responses": { "202": { "description": "Accepted - Report created, results will be delivered via webhook.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_criminal_report_created" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-regulated-criminal-reports", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/criminal_reports/{id}": { "get": { "summary": "Get regulated criminal report", "description": "Get a single regulated criminal report with a given id.", "tags": [ "Regulated Criminal Reports" ], "parameters": [ { "description": "The uuid identifying the regulated criminal report", "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "2b8313e8-4efd-45a1-b578-952b8313e890" }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_criminal_report" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-criminal-report-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/pre_adverse_actions": { "post": { "summary": "Create a pre-adverse action", "description": "Sends a pre-adverse action notification to the subject identified by `check_id`,\ngiving them the opportunity to dispute the results of their background check before\na final decision is made regarding their eligibility. This ensures compliance and\nfairness in the decision-making process.\n\nThis step is optional but must precede a final adverse action if used. Cannot be\nsubmitted after an adverse action has already been taken for this check.\n", "tags": [ "Regulated Adverse Action" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pre_adverse_action_request" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pre_adverse_action_response" } } } }, "400": { "description": "Validation error. One of:\n- `check_id` is missing, `email` is missing, or the regulated check does not exist for this account.\n- Adverse action is not enabled for the product configuration of this check.\n- The regulated check is more than 1 year old and cannot be used as the basis for a pre-adverse action; run a new regulated check first.\n- A pre-adverse action for this `email` was already initiated on this account within the last 30 days. Wait for the window to expire or use a different email.\n- The profile's first/last name is too common to act on without a middle name. Add a `middle_name` to the profile, or set `no_middle_name: true` to confirm there is no middle name.\n- The check has no criminal records to start an adverse action against.\n- One or more `disqualifying_records[].record_id` values do not appear on the check's records.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "409": { "description": "Conflict — one of:\n- a pre-adverse action has already been initiated for this check;\n- an adverse action has already been taken on this check, so a pre-adverse action can no longer be submitted;\n- the candidate already has a standing adverse action on file (a non-reversed final adverse action, or an active dispute, on any of their checks), which locks the profile; or\n- another of the candidate's checks already has an adverse-action cycle in progress (only one cycle per candidate at a time).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "500": { "$ref": "#/components/responses/error" } }, "callbacks": { "onPreAdverseActionCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Pre-Adverse Action Completion Webhook", "description": "Callback (webhook) triggered when the subject accepts a pre-adverse action\ndecision, transitioning it to the terminal `Closed` state.\n\nConfigure the destination URL (and optionally a signing key) via the\n`adverse_action_webhooks` settings on the account's adverse-action-enabled\nproduct configuration (`instant_criminal_regulated` or `county_criminal_regulated`).\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on\nsignature verification.\n", "requestBody": { "description": "Minimal payload identifying the pre-adverse action and its terminal status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pre-adverse-action-completed-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status to acknowledge receipt. We treat any 2xx as success and\nwill not retry the POST.\n" }, "4xx": { "description": "4xx responses are treated as client errors and may trigger retries depending on\nthe specific status code.\n" }, "5xx": { "description": "5xx responses are treated as server errors and will be retried automatically.\n" } } } } }, "onAdverseActionDisputeFiled": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Adverse Action Dispute Filed Webhook", "description": "Callback (webhook) triggered when a subject files a dispute against this pre-adverse\naction. The same event also fires for disputes against final adverse actions —\ninspect `data.adverse_action_type` (`pre_adverse_action` here) to tell them apart.\n\nConfigure the destination URL (and optionally a signing key) via the\n`adverse_action_webhooks` settings on the account's adverse-action-enabled\nproduct configuration (`instant_criminal_regulated` or `county_criminal_regulated`) — the same destination used for pre-adverse-action webhooks.\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on\nsignature verification.\n", "requestBody": { "description": "Minimal payload identifying the dispute, its parent (pre-)adverse action, and\ntype. Fetch full details (including dispute timestamps) via\n`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or\n`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by\n`data.adverse_action_type`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse-action-dispute-filed-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status to acknowledge receipt. We treat any 2xx as success and\nwill not retry the POST.\n" }, "4xx": { "description": "4xx responses are treated as client errors and may trigger retries depending on\nthe specific status code.\n" }, "5xx": { "description": "5xx responses are treated as server errors and will be retried automatically.\n" } } } } }, "onAdverseActionDisputeResolved": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Adverse Action Dispute Resolved Webhook", "description": "Callback (webhook) triggered when an admin resolves a dispute filed against this\npre-adverse action, either with changes to the report (`DisputeResolvedWithChanges`)\nor without (`DisputeResolvedWithoutChanges`). The same event also fires for final\nadverse actions — inspect `data.adverse_action_type` (`pre_adverse_action` here) to\ntell them apart.\n\nConfigure the destination URL (and optionally a signing key) via the\n`adverse_action_webhooks` settings on the account's adverse-action-enabled\nproduct configuration (`instant_criminal_regulated` or `county_criminal_regulated`).\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on\nsignature verification.\n", "requestBody": { "description": "Minimal payload identifying the dispute, its parent (pre-)adverse action, and\nresolution outcome. Fetch full details (including dispute timestamps) via\n`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or\n`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by\n`data.adverse_action_type`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse-action-dispute-resolved-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status to acknowledge receipt. We treat any 2xx as success and\nwill not retry the POST.\n" }, "4xx": { "description": "4xx responses are treated as client errors and may trigger retries depending on\nthe specific status code.\n" }, "5xx": { "description": "5xx responses are treated as server errors and will be retried automatically.\n" } } } } } }, "operationId": "post-regulated-pre-adverse-action", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/pre_adverse_actions/{pre_adverse_action_id}": { "get": { "summary": "Get a pre-adverse action", "description": "Retrieves a single pre-adverse action record by ID.", "tags": [ "Regulated Adverse Action" ], "parameters": [ { "name": "pre_adverse_action_id", "in": "path", "required": true, "description": "The UUID of the pre-adverse action record.", "schema": { "$ref": "#/components/schemas/uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pre_adverse_action_detail_response" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-pre-adverse-action-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/adverse_actions": { "post": { "summary": "Create an adverse action", "description": "Finalizes an adverse decision against the subject identified by `check_id`.\nUse this when your organization is declining a subject based in whole or in part\non the results of a Checkr background check.\n\nDelivers the required adverse action notice to the subject so they can seek\nassistance or initiate a dispute. In the event a dispute is resolved with changes\nto the report, Checkr will notify your organization so you can reassess\nthe subject's eligibility.\n\nMay be submitted with or without a prior pre-adverse action.\n\nIncluding `disqualifying_records` is optional but strongly recommended — FCRA\nrequires disclosing which records triggered the adverse decision.\n", "tags": [ "Regulated Adverse Action" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse_action_request" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse_action_response" } } } }, "400": { "description": "Validation error. One of:\n- `check_id` is missing, `email` is missing, or the regulated check does not exist for this account.\n- Adverse action is not enabled for the product configuration of this check.\n- The regulated check is more than 1 year old and cannot be used as the basis for an adverse action; run a new regulated check first.\n- An adverse action for this `email` was already initiated on this account within the last 30 days. Wait for the window to expire or use a different email.\n- The profile's first/last name is too common to act on without a middle name. Add a `middle_name` to the profile, or set `no_middle_name: true` to confirm there is no middle name.\n- The check has no criminal records to start an adverse action against.\n- One or more `disqualifying_records[].record_id` values do not appear on the check's records.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "409": { "description": "Conflict — one of:\n- an adverse action has already been initiated for this check;\n- the candidate already has a standing adverse action on file (a non-reversed final adverse action, or an active dispute, on any of their checks), which locks the profile; or\n- another of the candidate's checks already has an adverse-action cycle in progress (only one cycle per candidate at a time).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "500": { "$ref": "#/components/responses/error" } }, "callbacks": { "onAdverseActionDisputeFiled": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Adverse Action Dispute Filed Webhook", "description": "Callback (webhook) triggered when a subject files a dispute against a (pre-)adverse\naction. Fires for both pre-adverse and final-adverse disputes — inspect\n`data.adverse_action_type` to tell them apart.\n\nConfigure the destination URL (and optionally a signing key) via the\n`adverse_action_webhooks` settings on the account's adverse-action-enabled\nproduct configuration (`instant_criminal_regulated` or `county_criminal_regulated`) — the same destination used for pre-adverse-action webhooks.\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on\nsignature verification.\n", "requestBody": { "description": "Minimal payload identifying the dispute, its parent (pre-)adverse action, and\ntype. Fetch full details (including dispute timestamps) via\n`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or\n`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by\n`data.adverse_action_type`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse-action-dispute-filed-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status to acknowledge receipt. We treat any 2xx as success and\nwill not retry the POST.\n" }, "4xx": { "description": "4xx responses are treated as client errors and may trigger retries depending on\nthe specific status code.\n" }, "5xx": { "description": "5xx responses are treated as server errors and will be retried automatically.\n" } } } } }, "onAdverseActionDisputeResolved": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Adverse Action Dispute Resolved Webhook", "description": "Callback (webhook) triggered when an admin resolves a filed dispute, either with\nchanges to the report (`DisputeResolvedWithChanges`) or without\n(`DisputeResolvedWithoutChanges`). Fires for both pre-adverse and final-adverse\ndisputes — inspect `data.adverse_action_type` to tell them apart.\n\nConfigure the destination URL (and optionally a signing key) via the\n`adverse_action_webhooks` settings on the account's adverse-action-enabled\nproduct configuration (`instant_criminal_regulated` or `county_criminal_regulated`).\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on\nsignature verification.\n", "requestBody": { "description": "Minimal payload identifying the dispute, its parent (pre-)adverse action, and\nresolution outcome. Fetch full details (including dispute timestamps) via\n`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}` or\n`GET /v1/regulated/adverse_actions/{adverse_action_id}`, selected by\n`data.adverse_action_type`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse-action-dispute-resolved-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status to acknowledge receipt. We treat any 2xx as success and\nwill not retry the POST.\n" }, "4xx": { "description": "4xx responses are treated as client errors and may trigger retries depending on\nthe specific status code.\n" }, "5xx": { "description": "5xx responses are treated as server errors and will be retried automatically.\n" } } } } } }, "operationId": "post-regulated-adverse-action", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/adverse_actions/{adverse_action_id}": { "get": { "summary": "Get an adverse action", "description": "Retrieves a single adverse action record by ID.", "tags": [ "Regulated Adverse Action" ], "parameters": [ { "name": "adverse_action_id", "in": "path", "required": true, "description": "The UUID of the adverse action record.", "schema": { "$ref": "#/components/schemas/uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adverse_action_detail_response" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-adverse-action-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/county_checks": { "post": { "summary": "Create regulated county check", "description": "Create a new regulated county criminal check for a specific jurisdiction.\n\nThis endpoint initiates a county-level or statewide criminal background check using either\nprovided PII (personally identifiable information) or an existing profile. Results include\nlegal annotation checks at the record, case, and charge levels indicating whether items\nshould be included, investigated, or removed based on applicable regulations.\n\nA permissible purpose must be provided to comply with FCRA requirements.\n\n`county_fips_code` is required along with the state: provide a 5-digit FIPS code for a\ncounty-level check, or the literal `statewide` for a state-level check.\n\n{% partial file=\"/_partials/profile-id-county-precedence.md\" /%}\n\nRequired fields when providing PII (without profile_id):\n- first_name\n- last_name\n- dob\n- state\n- county_fips_code\n- filter_context\n- permissible_purpose\n\nWhen using a profile_id, state, county_fips_code, filter_context, and permissible_purpose are required.\n", "tags": [ "Regulated County Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_regulated_county" } ], "requestBody": { "$ref": "#/components/requestBodies/post-regulated-county-check-request-body" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_county_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } }, "callbacks": { "onSearchCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Regulated County Check Completion Webhook", "description": "Callback (webhook) triggered when the regulated county check reaches a terminal state.\n\nConfigure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive.\n\nThe payload is one of:\n- `county_check.completed` — results are available (`status: complete`).\n- `county_check.not_available` — the search was cancelled or could not be completed (`status: cancelled`).\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on signature verification.\n", "parameters": [ { "name": "X-Checkr-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the raw request body, formatted as `sha256=`.\nThis header is always present. Verify it against the raw body using a timing-safe\ncomparison to confirm the payload's authenticity.\n\nWe strongly recommend configuring a dedicated webhook signing key (shared secret) with your\nCheckr Account Executive. A dedicated secret limits the blast radius if your webhook\nendpoint is compromised. If no dedicated signing key is configured, your account's client\nsecret is used as a fallback — but reusing the client secret here broadens exposure of a\nhigh-value credential, so a dedicated key is preferred.\n\nTo mitigate replay attacks, deduplicate on the event `id` and ignore events you have already\nprocessed. This is retry-safe, since retries reuse the same `id` and the original `created_at`.\nIf you additionally enforce a `created_at` freshness window, size it to cover the full delivery\nretry/backoff window so legitimate retries are not rejected.\n", "schema": { "type": "string", "example": "sha256=4f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778899aabbccddeeff0" } } ], "requestBody": { "description": "Payload containing the regulated county check result or not-available notification", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/county-check-completed-event-body" }, { "$ref": "#/components/schemas/county-check-not-available-event-body" } ] } } } }, "responses": { "2XX": { "description": "Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.\nWe treat any 2xx as success and will not retry the POST.\n" }, "4XX": { "description": "HTTP status codes in the 4xx range indicate client errors (e.g., 400 Bad Request, 401 Unauthorized).\nReturning a 4xx status may result in retries depending on the specific status code.\n" } } } } } }, "operationId": "post-regulated-county-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/county_checks/{regulated_county_check_id}": { "get": { "summary": "Get regulated county check", "description": "Get a single regulated county check with a given id.", "tags": [ "Regulated County Checks" ], "parameters": [ { "description": "The uuid identifying the regulated county check", "$ref": "#/components/parameters/regulated_county_check_id" }, { "$ref": "#/components/parameters/include_regulated_county" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_county_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-regulated-county-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/county_checks": { "post": { "summary": "Create county check", "description": "Create a new county criminal check for a county jurisdiction, or a state-level criminal check when\n`county_fips_code` is the literal `statewide` (case-insensitively).\n\nThis endpoint supports three mutually exclusive search modes:\n\n{% partial file=\"/_partials/profile-id-county-precedence.md\" /%}\n\n**PII search** — provide subject identifying information directly:\n- first_name (required)\n- last_name (required)\n- dob (required)\n- state (required)\n- county_fips_code (required) — 5-digit county FIPS, or `statewide` for a state-level search\n\n**Profile search** — reference an existing profile:\n- profile_id (required)\n- state (required)\n- county_fips_code (required) — 5-digit county FIPS, or `statewide` for a state-level search\n\n**Case number search** — search by a specific court case number (NC and MN only):\n- case_number (required) — letters, numbers, spaces, and hyphens only\n- state (required) — `NC` or `MN`\n- county_fips_code (required) — 5-digit county FIPS\n\nThese three modes are mutually exclusive — do not combine `case_number` with `first_name`/`last_name`, `dob`, `profile_id`, or `lookback_period_in_years` in the same request.\n", "tags": [ "County Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_profile_only" } ], "requestBody": { "$ref": "#/components/requestBodies/post-county-check-request-body" }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/county_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } }, "callbacks": { "onSearchCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "County Check Completion Webhook", "description": "Callback (webhook) triggered when the county criminal check reaches a terminal state.\n\nConfigure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive.\n\nThe payload is one of:\n- `county_criminal.completed` — results are available (`status: complete`).\n- `county_criminal.not_available` — the search was cancelled or could not be completed (`status: cancelled`).\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on signature verification.\n", "parameters": [ { "name": "X-Checkr-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature of the raw request body, formatted as `sha256=`.\nThis header is always present. Verify it against the raw body using a timing-safe\ncomparison to confirm the payload's authenticity.\n\nWe strongly recommend configuring a dedicated webhook signing key (shared secret) with your\nCheckr Account Executive. A dedicated secret limits the blast radius if your webhook\nendpoint is compromised. If no dedicated signing key is configured, your account's client\nsecret is used as a fallback — but reusing the client secret here broadens exposure of a\nhigh-value credential, so a dedicated key is preferred.\n\nTo mitigate replay attacks, deduplicate on the event `id` and ignore events you have already\nprocessed. This is retry-safe, since retries reuse the same `id` and the original `created_at`.\nIf you additionally enforce a `created_at` freshness window, size it to cover the full delivery\nretry/backoff window so legitimate retries are not rejected.\n", "schema": { "type": "string", "example": "sha256=4f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778899aabbccddeeff0" } } ], "requestBody": { "description": "Payload containing the county check result or not-available notification", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/county-criminal-completed-event-body" }, { "$ref": "#/components/schemas/county-criminal-not-available-event-body" } ] } } } }, "responses": { "2XX": { "description": "Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.\nWe treat any 2xx as success and will not retry the POST.\n" }, "4XX": { "description": "HTTP status codes in the 4xx range indicate client errors (e.g., 400 Bad Request, 401 Unauthorized).\nReturning a 4xx status may result in retries depending on the specific status code.\n" } } } } } }, "operationId": "post-county-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/county_checks/{county_check_id}": { "get": { "summary": "Get county check", "description": "Get a single county check with a given id.", "tags": [ "County Checks" ], "parameters": [ { "description": "The uuid identifying the county check", "$ref": "#/components/parameters/county_check_id" }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/county_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-county-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/county_checks/{county_check_id}/cancel": { "post": { "summary": "Cancel county check", "description": "Cancel an existing county check that is in a pending state.\n\nA reason must be provided for the cancellation. Only checks that are\ncurrently in 'pending' status can be cancelled.\n", "tags": [ "County Checks" ], "parameters": [ { "description": "The uuid identifying the county check", "$ref": "#/components/parameters/county_check_id" }, { "$ref": "#/components/parameters/include_profile_only" } ], "requestBody": { "$ref": "#/components/requestBodies/post-county-check-cancel-request-body" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/county_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } }, "operationId": "post-county-check-cancel", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/criminal_checks": { "get": { "summary": "Get criminal checks", "description": "Get a set of criminal checks. Results are only available after the check completes (`completed_at` is set).\n\nAlways check `completed_at` before interpreting the `results` array. An empty `results` array is ambiguous unless `completed_at` is set: when `completed_at` is `null` the check is still pending and results have not yet been populated, whereas an empty `results` array on a check with `completed_at` set means the check completed with no records found.\n", "tags": [ "Criminal Checks" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_check_index" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/criminal_check" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-criminal-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create criminal check", "description": "Create a new criminal check. The check is created and processed asynchronously; results are not returned in the create response.\n\n{% partial file=\"/_partials/profile-id-pii-mutual-exclusivity-reference-id-allowed.md\" /%}\n\n**Important Notes:**\n- Results are NOT returned in the HTTP response (returns 202 Accepted)\n- Results become available via GET once the check completes\n- When a webhook destination_url is configured on the product configuration, results are also delivered asynchronously via webhook\n", "tags": [ "Criminal Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_profile_only" } ], "requestBody": { "$ref": "#/components/requestBodies/post-criminal-check-request-body" }, "responses": { "202": { "description": "Accepted - Check created. Results become available via GET once complete, and via webhook when configured.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the created check" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Status of the check (always 'pending' on creation)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the check was created" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "callbacks": { "onSearchCompleted": { "https://example.com/my-webhook-endpoint": { "post": { "summary": "Criminal Check Completion Webhook", "description": "Callback (webhook) triggered when the criminal check search is finished. \n\nConfigure this webhook URL in your product configuration settings, either in the dashboard under Configuration or with your Checkr Account Executive. The webhook is optional; you may also retrieve results with GET once the check completes. \n\nThe payload contains the results for the `criminal_check`. When configured, results are delivered asynchronously via webhook. See the schema below for details.\n\nRefer to the main [Webhooks](./index.md#webhooks) documentation for details on signature verification.\n", "requestBody": { "description": "Payload containing the criminal check results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/criminal-check-completed-event-body" } } } }, "responses": { "2xx": { "description": "Return any 2xx status (e.g. 200 OK, 201 Created, 204 No Content) when you successfully process the callback.\nWe treat any 2xx as success and will not retry the POST.\n" }, "4xx": { "description": "HTTP status codes in the 4xx range indicate client errors (e.g., 400 Bad Request, 401 Unauthorized).\nReturning a 4xx status may result in retries depending on the specific status code.\n" } } } } } }, "operationId": "post-criminal-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/criminal_checks/{criminal_check_id}": { "get": { "summary": "Get criminal check", "description": "Get a single criminal check with a given id. Results are only visible after the check completes (`completed_at` is set).\n\nAlways check `completed_at` before interpreting the `results` array. An empty `results` array is ambiguous unless `completed_at` is set: when `completed_at` is `null` the check is still pending and results have not yet been populated, whereas an empty `results` array on a check with `completed_at` set means the check completed with no records found.\n", "tags": [ "Criminal Checks" ], "parameters": [ { "description": "the uuid identifying the criminal check", "name": "criminal_check_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/include_check_show" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/criminal_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-criminal-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/profile_criminal_checks": { "post": { "x-badges": [ { "name": "Beta", "color": "purple", "position": "before" } ], "summary": "Create profile criminal check", "description": "Create a new profile criminal check. Unlike Instant Criminal Checks, `results` is an array\nof matched identities (profiles) with their own nested records, rather than a flat records\narray -- so a customer can first review which identity matched before drilling into its\nrecords.\n\n{% partial file=\"/_partials/beta-provisional-notice.md\" /%}\n\n{% partial file=\"/_partials/profile-id-pii-mutual-exclusivity.md\" /%}\n", "tags": [ "Profile Criminal Checks" ], "parameters": [ { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile" ], "x-enumDescriptions": { "profile": "Embeds the full submitted profile object in place of `profile_id`." } } } } ], "requestBody": { "$ref": "#/components/requestBodies/post-profile-criminal-check-request-body" }, "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profile_criminal_check" } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-profile-criminal-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/profile_criminal_checks/{check_id}": { "get": { "x-badges": [ { "name": "Beta", "color": "purple", "position": "before" } ], "summary": "Get profile criminal check", "description": "Get a single profile criminal check with a given id.\n\n{% partial file=\"/_partials/beta-provisional-notice.md\" /%}\n", "tags": [ "Profile Criminal Checks" ], "parameters": [ { "description": "the uuid identifying the check", "$ref": "#/components/parameters/check_id" }, { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile" ], "x-enumDescriptions": { "profile": "Embeds the full submitted profile object in place of `profile_id`." } } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/profile_criminal_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-profile-criminal-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/eviction_checks": { "get": { "summary": "Get eviction checks", "description": "Get a list of previously created eviction checks.", "tags": [ "Regulated Eviction Checks" ], "parameters": [ { "description": "limit the number of records returned", "$ref": "#/components/parameters/limit" }, { "description": "skip a number of records before returning (for paging)", "$ref": "#/components/parameters/skip" }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/eviction_check" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-eviction-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] }, "post": { "summary": "Create eviction check", "description": "Create a new eviction check.\n\nEviction checks search court records for eviction filings associated with the provided PII or profile. Results are returned synchronously in the response body.\n\n{% partial file=\"/_partials/profile-id-pii-eviction-checks.md\" /%}\n\nProviding `dob` is strongly encouraged — it significantly reduces false positives when multiple people share a name.\n\nA permissible purpose must be provided to comply with FCRA requirements.\n", "tags": [ "Regulated Eviction Checks" ], "parameters": [ { "$ref": "#/components/parameters/include_profile_only" } ], "requestBody": { "$ref": "#/components/requestBodies/post-regulated-eviction-check-request-body" }, "responses": { "201": { "description": "Created.\nWhen the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eviction_check" }, "examples": { "with_results": { "summary": "Response with eviction records found", "value": { "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080", "created_at": "2024-03-15T10:22:04Z", "completed_at": "2024-03-15T10:22:05Z", "results": [ { "first_name": "Patricia", "last_name": "Holloway", "middle_name": "Ann", "address": "482 Birch Lane", "city": "Springfield", "state": "IL", "zip_code": "62704", "zone": "Springfield Metro", "subject": { "full_name": "Patricia Ann Holloway", "dob": "1985-03-14", "address": "482 Birch Lane, Springfield, IL 62704", "aliases": "P. Holloway", "state": "IL", "jurisdiction": "Sangamon County", "source": "IL_SANG_EVICT", "case_number": "2023-EV-004471", "category": "Eviction", "status": "Active", "comments": null }, "case": { "court": "Sangamon County Circuit Court", "case_number": "2023-EV-004471", "filing_date": "2023-06-12", "notice_type": "Forcible Entry and Detainer", "agency_state": "IL", "agency_county": "Sangamon", "dismissal_date": null, "default_judgement": true, "restored_premises": false, "plaintiff": { "name": "Riverstone Property Management LLC", "phone": "217-555-0182", "attorney": "Gregory L. Marsh", "attorney_phone": "217-555-0199" }, "judgement": { "date": "2023-07-05", "amount_cents": 347500, "type": "Judgment for Plaintiff", "for": "Plaintiff", "satisfaction_amount_cents": null, "release_date": null } } } ], "run_notes": [ "changed last_name from 'Holloway Jr' to 'Holloway'" ] } }, "no_results": { "summary": "Response with no eviction records found", "value": { "id": "7c1a2d3b-9fae-41bc-8d2e-6f4c5e7b8a90", "profile_id": "5e8f3c12-1b47-4d9a-a6e5-2c8d4f6e1b34", "created_at": "2024-03-15T10:25:00Z", "completed_at": "2024-03-15T10:25:01Z", "results": [], "run_notes": [] } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/rate-limit-exceeded" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "post-eviction-checks", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/regulated/eviction_checks/{eviction_check_id}": { "get": { "summary": "Get eviction check", "description": "Retrieve a previously created eviction check by its ID.", "tags": [ "Regulated Eviction Checks" ], "parameters": [ { "name": "eviction_check_id", "in": "path", "required": true, "description": "The UUID identifying the eviction check.", "schema": { "$ref": "#/components/schemas/uuid" } }, { "$ref": "#/components/parameters/include_profile_only" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eviction_check" } } } }, "401": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-eviction-check-by-id", "security": [ { "get-bearer-token-using-oauth2": [] } ] } }, "/test_scenarios": { "get": { "summary": "List test scenarios", "description": "Lists the deterministic mock scenarios your account can exercise, with the exact inputs\nthat trigger each one and a description of what the resulting response represents.\n\nThis endpoint is the source of truth for which inputs produce which mock response. The\n[Test Accounts](./test-accounts.md) guide covers the surrounding behavior — matching\nrules, async simulation, error handling, worked examples — but deliberately does not\nenumerate scenarios, so fetch them here rather than copying values out of a docs page.\n\nSend **every** field in `inputs`, not just the fields in `match_keys`. Some are required\nfor request validation, and some are compared against the fixture during identity\nmatching, even though they are not what selects the scenario. `match_keys` lists the\nfields that choose which scenario you get.\n\nA scenario is listed only when both of the following are true:\n\n1. your account's environment is one where that product's mock path runs, and\n2. the scenario's product is enabled on your account.\n\nBecause of the first rule, **accounts outside the Test environment receive an empty\narray**. Pilot and Live requests are served by real data sources, so there is no mock data\nto advertise. This is a successful empty response, not an error. See\n[Accounts](./accounts.md) for the environment model.\n\nResults are not paginated: the catalog is a small, fixed set that changes only when we\npublish new scenarios.\n", "tags": [ "Test Scenarios" ], "parameters": [ { "name": "product", "in": "query", "required": false, "description": "Restrict results to a single product, for example `instant_criminal`,\n`county_criminal` or `motor_vehicle_report`. Returns an empty array if the product is\nnot enabled on your account.\n", "schema": { "type": "string" }, "example": "county_criminal" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/test_scenario" } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } }, "operationId": "get-test-scenarios", "security": [ { "get-bearer-token-using-oauth2": [] } ] } } }, "components": { "parameters": { "limit": { "name": "limit", "description": "limit the number of records returned", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 10 } }, "skip": { "name": "skip", "description": "skip a number of records before returning (for paging)", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 0 } }, "include": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, "include_profile_only": { "name": "include[]", "description": "Embed the profile in the response in place of `profile_id`.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] } } }, "include_check_index": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "results_found" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`.", "results_found": "Returns `results_found` (boolean) instead of the full `results` array." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] }, "single_results_found": { "summary": "Single value", "value": [ "results_found" ] }, "multiple_profile_and_results_found": { "summary": "Multiple values", "value": [ "profile", "results_found" ] } } }, "include_check_show": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "rulesets_applied" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`.", "rulesets_applied": "Embeds the rulesets applied when filtering this check's results." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] }, "multiple_profile_and_rulesets_applied": { "summary": "Multiple values", "value": [ "profile", "rulesets_applied" ] } } }, "include_regulated_index": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "results_found", "review" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`.", "results_found": "Returns `results_found` (boolean) instead of the full `results` array.", "review": "Embeds the regulated check review object (accept/decline/dispute status)." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] }, "single_results_found": { "summary": "Single value", "value": [ "results_found" ] }, "multiple_profile_and_review": { "summary": "Multiple values", "value": [ "profile", "review" ] } } }, "include_regulated_show": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "rulesets_applied", "review" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`.", "rulesets_applied": "Embeds the rulesets applied when filtering this check's results.", "review": "Embeds the regulated check review object (accept/decline/dispute status)." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] }, "multiple_profile_and_review": { "summary": "Multiple values", "value": [ "profile", "review" ] } } }, "include_regulated_county": { "name": "include[]", "description": "Request optional response fields. Repeat the parameter for multiple values.", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "review" ], "x-enumDescriptions": { "profile": "Embeds the full profile object in place of `profile_id`.", "review": "Embeds the regulated check review object (accept/decline/dispute status)." } } }, "examples": { "single_profile": { "summary": "Single value", "value": [ "profile" ] }, "multiple_profile_and_review": { "summary": "Multiple values", "value": [ "profile", "review" ] } } }, "check_id": { "name": "check_id", "description": "the uuid identifying the check", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" } }, "driver_check_id": { "name": "driver_check_id", "description": "the uuid identifying the driver check", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" } }, "identity_verification_id": { "name": "identity_verification_id", "description": "the uuid identifying the identity verification", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" } }, "profile_id": { "name": "profile_id", "description": "the uuid identifying the profile", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-b578-45a1-4efd-952b8313e890" } }, "county_check_id": { "name": "county_check_id", "description": "the uuid identifying the county check", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" } }, "regulated_county_check_id": { "name": "regulated_county_check_id", "description": "the uuid identifying the regulated county check", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" } }, "bulk_upload_id": { "name": "bulk_upload_id", "description": "the uuid identifying the bulk upload", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "2b8313e8-b578-45a1-4efd-952b8313e890" } }, "unmask_ssn": { "name": "unmask_ssn", "description": "Controls whether SSN values in `results.requested_profile.ssn` (and\n`results_v2.requested_profile.ssn` for driver license status checks) are\nreturned in full or masked as `XXX-XX-{last4}`.\n\nUsed by driver check endpoints. For identity verification endpoints, see\n`unmask_ssn_identity_verification` instead — precedence rules differ.\n\nWhen omitted, the account's product configuration `unmask_ssn` setting\ndetermines whether SSNs are unmasked. When explicitly set to `true` or\n`false`, the query parameter overrides the product configuration.\n\nDefaults to masked when the product configuration has no `unmask_ssn`\nsetting.\n", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "unmask_ssn_identity_verification": { "name": "unmask_ssn", "description": "For `personal_identity_records` results, controls whether SSN values in\n`results.people[].ssn` are returned in full or masked as `XXX-XX-{last4}`.\n\nUsed by identity verification endpoints only. Driver check endpoints use\n`unmask_ssn` instead — see that parameter for precedence rules that apply\nto `results.requested_profile.ssn`.\n\nWhen the product configuration has an explicit `unmask_ssn` setting (available\nfor `personal_identity_records` only), that setting takes precedence over this\nquery parameter.\n\nWhen no product configuration setting exists, `false` or omitted returns masked\nSSN values and `true` returns full SSN values.\n\nIf an SSN value is null or empty, it remains null regardless of this parameter.\n", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } }, "schemas": { "uuid": { "type": "string", "format": "uuid", "description": "A universally unique identifier (UUID) in standard format.", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" }, "datetime": { "type": "string", "format": "date-time", "description": "An ISO 8601 formatted date-time string.", "example": "2020-01-01T00:00:00Z" }, "date": { "type": "string", "format": "date", "description": "An ISO 8601 formatted date string.", "example": "2020-01-01" }, "date_string_complete": { "description": "A date in the form YYYYMMDD.", "type": "string", "pattern": "\\d{8}", "minLength": 8, "maxLength": 8, "example": "19950401" }, "date_string_partial": { "description": "A date or partial date in the form YYYYMMDD.\nSince some dates are partial, they may be represented as YYYY0000 or 0000MMDD or YYYYMM00.\n", "type": "string", "pattern": "\\d{8}", "minLength": 8, "maxLength": 8, "example": "19950401" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "A two-letter country code in ISO 3166-1 alpha-2 format.", "example": "US" }, "state_code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "A two-letter US state code.", "example": "CA" }, "zip_code": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$", "description": "US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).", "example": "94105" }, "address": { "type": "object", "description": "A US postal address supplied in a **request** (for example on check create or profile create/update).\nWhen this object is present, `street`, `city`, `state`, and `zip_code` are required.\n", "properties": { "street": { "type": "string", "description": "Street address, including house/building number and street name.\nApartment or unit numbers may be included; they are stored but are not used for criminal-record address matching.\n", "example": "123 Main St" }, "city": { "type": "string", "description": "The name of the city or municipality.", "example": "Frankfort" }, "state": { "description": "The two-letter US state code where the address is located.", "$ref": "#/components/schemas/state_code" }, "zip_code": { "description": "The US postal ZIP code for the address.", "$ref": "#/components/schemas/zip_code" }, "country": { "description": "The two-letter country code, typically \"US\" for United States addresses.", "$ref": "#/components/schemas/country_code" } }, "required": [ "street", "city", "state", "zip_code" ] }, "address_as_reported": { "type": "object", "description": "An address as it appears on a criminal or registry **record** returned from a data source.\nFormat and completeness vary by source. Only fields present on the source record are returned;\ndo not assume every address object includes `street`, `city`, `state`, or `zip_code`.\n", "properties": { "street": { "type": "string", "description": "Street or location line as reported by the source. May be a free-form string rather than a\nnormalized postal address (for example, a registry status message).\n", "example": "123 Main St" }, "city": { "type": "string", "description": "City or municipality when reported by the source.", "example": "Frankfort" }, "state": { "type": "string", "description": "State as reported by the source, if any.", "example": "KY" }, "zip_code": { "type": "string", "description": "ZIP code as reported by the source, if any.", "example": "40601" }, "country": { "type": "string", "description": "Country as reported by the source, if any.", "example": "US" } } }, "addresses": { "type": "array", "minItems": 1, "maxItems": 10, "description": "**Request only.** Array of addresses supplied by the caller. Index 0 is the primary address.\nWhen the property is provided, at least one address entry is required.\nFor check requests, records may be matched against any address in the array.\nThe singular `address` field remains supported for backwards compatibility and maps to the primary address.\n", "items": { "$ref": "#/components/schemas/address" } }, "email_string": { "type": "string", "format": "email", "description": "An email address.", "example": "john.doe@example.com" }, "phone_string": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "A phone number in the form +[country code][number including area code].\n([E.164 format](https://en.wikipedia.org/wiki/E.164)).\nPlease note that U.S. phone numbers have a country code of \"1\" so all U.S. phone numbers ought to start with \"+1\".\nA U.S. number supplied in national format (for example \"(415) 555-0123\") is normalized to E.164\non write. If the value cannot be parsed as a valid phone number, the API returns a 400 with a\n`validation_error`.\n", "example": "+14155552671" }, "ssn_string": { "type": "string", "pattern": "^\\d{3}-?\\d{2}-?\\d{4}$", "description": "A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.", "example": "123-45-6789" }, "custom_id_string": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "description": "An identifier of your choice, if you wish to use one. Limited to 64 alphanumeric characters, underscores, and hyphens.", "example": "my-custom-id-123" }, "reference_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "description": "A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.", "example": "ref-123" }, "ruleset_id": { "description": "Identifier of an existing ruleset containing filtering rules. To set up account rulesets, please reach out to your Checkr Account Executive or Customer Success representative to set up the configuration.", "type": "string", "format": "uuid", "example": "d16e88e6-aacc-4c42-9cd2-58a93dc9d8af" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. When both `ruleset_id` and\n`ruleset_ids` are provided, they are merged and de-duplicated before applying.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } }, "profile_id": { "type": "string", "format": "uuid", "description": "Identifier of an existing profile containing search criteria.", "example": "2b8313e8-4efd-45a1-b578-952b8313e890" }, "input_type": { "title": "input_type", "type": "string", "description": "The type of input being provided for the search. Can be either a person's information or an address.", "enum": [ "person", "address" ], "default": "person" }, "input_type_address": { "title": "input_type", "type": "string", "description": "Specifies that the input type is an address. Used when searching by address only.", "enum": [ "address" ] }, "source_states": { "description": "An array of state abbreviations. Only records which come from a given source state are included in the results. Note that some sources are not tagged as coming from a single source state, so records from those sources will always be included. Sex offender registry records and most watchlist records are not tagged with a source state, and so will appear in the results regardless of this flag. \n", "type": "array", "items": { "$ref": "#/components/schemas/state_code" } }, "order_by": { "title": "order_by", "type": "string", "description": "Specifies the field to sort the results by. Currently only supported for 'photo_urls'.", "enum": [ "photo_urls" ], "example": "photo_urls" }, "error": { "type": "object", "description": "A standard error object following JSON:API error format.", "properties": { "code": { "type": "string", "description": "A machine-readable error code.", "example": "invalid_request" }, "title": { "type": "string", "description": "A human-readable error title.", "example": "Invalid Request" }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string", "description": "A JSON Pointer [RFC6901] to the associated entity in the request document.", "example": "/data/attributes/first_name" } } } }, "required": [ "code", "title" ] }, "errors": { "type": "array", "description": "An array of error objects.", "items": { "$ref": "#/components/schemas/error" } }, "token": { "type": "object", "description": "OAuth 2.0 access token response from `POST /accounts/token`\n(client credentials). Pass `access_token` as a Bearer token on API requests.\n", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "The JWT access token to use for API requests.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "The type of token, always \"Bearer\".", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Seconds until the token expires. Typically `86400` (24 hours).\nRequest a new token when this elapses — this endpoint does not issue\nrefresh tokens.\n", "example": 86400 }, "scope": { "type": "string", "description": "Space-separated OAuth scopes granted to this client (from Auth0 client\nconfiguration). Product check endpoints generally require a valid token\nand an enabled product configuration rather than a specific scope.\n", "example": "read:account create:account delete:account" } } }, "oauth_token_error": { "type": "object", "description": "OAuth 2.0 error body returned when `POST /accounts/token` fails upstream\n(Auth0). Distinct from the JSON:API `errors` array used on other endpoints.\n", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "OAuth error code (for example `access_denied` or `invalid_client`).", "example": "access_denied" }, "error_description": { "type": "string", "description": "Human-readable explanation from the authorization server.", "example": "Unauthorized" } } }, "check_review": { "type": "object", "description": "Customer accept/decline/dispute state for a regulated check.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "check_id": { "$ref": "#/components/schemas/uuid", "description": "The check this verdict applies to." }, "status": { "type": "string", "enum": [ "accepted", "declined", "disputed" ], "x-enumDescriptions": { "accepted": "The customer accepted the check results.", "declined": "The customer declined the check results (adverse action initiated).", "disputed": "The subject disputed an adverse action notice." } }, "decided_at": { "$ref": "#/components/schemas/datetime" }, "decided_by_user_id": { "$ref": "#/components/schemas/uuid", "description": "User who recorded the accept/decline decision." }, "adverse_action_id": { "description": "Associated adverse action record when status is `declined` or `disputed`; otherwise null.", "oneOf": [ { "$ref": "#/components/schemas/uuid" }, { "type": "null" } ] } }, "required": [ "id", "check_id", "status", "decided_at", "decided_by_user_id" ] }, "ruleset_applied": { "type": "object", "description": "A ruleset applied when filtering check results.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "name": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "default": { "type": "boolean" }, "shared": { "type": "boolean" }, "rules": { "type": "object", "description": "Rules engine definition used to filter results.", "additionalProperties": true }, "created_at": { "$ref": "#/components/schemas/datetime" }, "updated_at": { "$ref": "#/components/schemas/datetime" }, "account": { "$ref": "#/components/schemas/ruleset_applied_account" } }, "required": [ "id", "name", "enabled", "default", "shared", "rules", "created_at", "updated_at" ] }, "ruleset_applied_account": { "description": "Account that owns the ruleset. Null when not applicable.", "oneOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "company_name": { "type": "string" }, "uri_name": { "type": "string" } }, "required": [ "id", "company_name", "uri_name" ] }, { "type": "null" } ] }, "bulk_upload_product_name": { "type": "string", "description": "Product configuration name for the upload. The account must have this product\nenabled. Supported values:\n\n- `instant_criminal` — synchronous Instant Criminal checks\n- `instant_criminal_regulated` — synchronous Regulated Instant Criminal checks\n- `county_criminal` — asynchronous County Criminal checks\n- `county_criminal_regulated` — asynchronous Regulated County Criminal checks\n- `sex_offender_registry` — synchronous Sex Offender Registry checks\n", "enum": [ "instant_criminal", "instant_criminal_regulated", "county_criminal", "county_criminal_regulated", "sex_offender_registry" ], "example": "county_criminal" }, "bulk_upload_state": { "type": "string", "description": "Lifecycle state of the bulk upload.\n\nCounty products may remain in `processing` while individual rows await\nprovider results (`awaiting_results` on each item). The upload moves to\n`completed` once every row is terminal and result files are generated.\n", "enum": [ "submitted", "validating", "invalid_input", "validated", "processing", "completed", "failed" ], "example": "processing" }, "permissible_purpose": { "type": "string", "description": "The permissible purpose for requesting this criminal record check, as required by the Fair Credit Reporting Act (FCRA).\nThis must be provided for all regulated instant criminal checks to ensure compliance with federal regulations.\n", "enum": [ "Court Order", "Consumer Instruction", "Credit Transaction", "Employment", "Insurance Underwriting", "Benefit Eligibility", "Credit Risk", "Consumer Initiated", "Account Review", "Govt Chargecard", "Child Support", "Agency Liquidation" ], "example": "Employment" }, "jurisdiction": { "type": "object", "description": "A geographic jurisdiction specified by state, and optionally county and city.", "properties": { "state": { "$ref": "#/components/schemas/state_code" }, "county": { "type": "string", "description": "The county name within the state.", "example": "Los Angeles" }, "city": { "type": "string", "description": "The city name within the jurisdiction.", "example": "San Francisco" } } }, "filter_domain": { "type": "string", "description": "The legal-filtering domain to apply to this check (for example, employment vs. tenancy rules).\n\nThis is only needed when your account is configured to allow multiple filter domains.\nMost callers do not need to set this — a default domain is applied automatically based on\nyour account's configuration. When your account does allow choosing a domain per call, only\na limited, pre-approved set of values is accepted; contact Checkr to configure which domains\nyour account can use.\n", "enum": [ "employment", "long term tenancy", "short term tenancy", "eviction", "other" ], "example": "employment" }, "filter_context": { "type": "object", "description": "Context information used to determine which legal rules apply when filtering check results.\nJurisdictions help identify applicable state and local regulations that may affect\nwhich records can be reported.\n", "properties": { "candidate_jurisdiction": { "description": "The jurisdiction where the candidate (subject of the check) is located.", "$ref": "#/components/schemas/jurisdiction" }, "decider_jurisdiction": { "description": "The jurisdiction where the decision-maker (employer/requester) is located.", "$ref": "#/components/schemas/jurisdiction" }, "property_jurisdiction": { "description": "The jurisdiction of the property involved (for tenancy-related checks).", "$ref": "#/components/schemas/jurisdiction" }, "filter_domain": { "$ref": "#/components/schemas/filter_domain" } }, "required": [ "candidate_jurisdiction" ] }, "bulk_upload_settings": { "type": "object", "description": "Upload-level settings persisted on the bulk upload (`additional_settings`).\nWhich fields apply depends on `product_name`. Unknown keys are ignored by the API\n(strong parameters); only the fields below are accepted.\n\nSend nested multipart fields using Rails bracket notation, for example\n`settings[permissible_purpose]=Employment` and\n`settings[filter_context][candidate_jurisdiction][state]=CA`.\n\n**Instant Criminal** (`instant_criminal`): `ruleset_id` / `ruleset_ids`, optional\n`provider_name`.\n\n**Regulated Instant Criminal** (`instant_criminal_regulated`): same as instant, plus\nrequired `permissible_purpose`, optional `regulated_user_type` and `filter_context`.\n\n**County Criminal** (`county_criminal`): `ruleset_id` / `ruleset_ids`,\n`lookback_period_in_years`, `include_null_date_of_birth`. Per-row jurisdiction\n(`state`, `county_fips_code`) and `dob` belong in the CSV, not here.\n\n**Regulated County Criminal** (`county_criminal_regulated`): county settings plus\nrequired `permissible_purpose`, optional `regulated_user_type` and `filter_context`.\nPer-row `dob` is required in the CSV (FCRA compliance).\n\n**Sex Offender Registry** (`sex_offender_registry`): `ruleset_id` / `ruleset_ids`,\noptional `provider_name`. Same person (name + DOB) search as Instant Criminal,\nnarrowed to sex offender registry records.\n", "properties": { "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "provider_name": { "type": "string", "description": "Optional provider override for Instant Criminal and Sex Offender Registry bulk\nuploads only. Single-check Instant Criminal and Sex Offender Registry requests\ndo not expose this field publicly; prefer account product configuration unless\nCheckr directs otherwise.\n", "example": "tessera" }, "lookback_period_in_years": { "description": "Optional number of years to look back for criminal records (county products only).\nIf not provided, the default lookback period configured for the account will be used.\n", "type": "integer", "minimum": 1, "maximum": 99, "example": 7 }, "include_null_date_of_birth": { "description": "Optional override for this upload indicating whether county searches include\nrecords with a null date of birth. If omitted, your account's default setting\nis used (or `true` if not configured).\n", "type": "boolean", "example": true }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose" }, "regulated_user_type": { "type": "string", "description": "Optional regulated user type applied to every row in a regulated bulk upload.\nSingle regulated check endpoints resolve this from the account's product\nconfiguration and do not accept it on the request body; bulk upload (and\nbatch runs) allow an explicit upload-level override for filtering exposure.\n", "example": "regulated" }, "filter_context": { "$ref": "#/components/schemas/filter_context" } }, "additionalProperties": false }, "bulk_upload_error": { "type": "object", "description": "Validation or processing error associated with the upload or a row.", "properties": { "code": { "type": "string", "example": "validation_error" }, "title": { "type": "string", "description": "Human-readable error summary returned to the client. For stored hash errors this\nis typically the `detail` message from validation or processing (not a raw\ndatabase or stack trace).\n", "example": "missing required column header" }, "source": { "type": [ "string", "null" ], "description": "Optional JSON pointer or column name pointing at the problem field.", "example": "state" } }, "required": [ "code", "title" ] }, "bulk_upload_file": { "type": "object", "description": "Metadata for an attached CSV or XLSX file, including a relative download URL.", "properties": { "filename": { "type": "string", "example": "county_batch.csv" }, "content_type": { "type": "string", "example": "text/csv" }, "byte_size": { "type": "integer", "example": 2048 }, "human_readable_size": { "type": "string", "example": "2 KB" }, "download_url": { "type": "string", "description": "Path (or absolute URL when the API includes a host) to download the file.\nOriginal CSV uses `/v1/bulk_uploads/{bulk_upload_id}/original`. Result CSV uses\n`/v1/bulk_uploads/{bulk_upload_id}/results?format=csv`. Detailed XLSX uses\n`/v1/bulk_uploads/{bulk_upload_id}/results?format=xlsx`.\n", "example": "/v1/bulk_uploads/2b8313e8-b578-45a1-4efd-952b8313e890/original" } }, "required": [ "filename", "content_type", "byte_size", "human_readable_size", "download_url" ] }, "bulk_upload": { "type": "object", "description": "A CSV batch of checks for a single product. Instant products complete each row\nwhen the factory returns; county products submit asynchronously and finalize\nafter every row reaches a terminal state.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "account_id": { "$ref": "#/components/schemas/uuid" }, "product_configuration_id": { "$ref": "#/components/schemas/uuid" }, "product_configuration_name": { "$ref": "#/components/schemas/bulk_upload_product_name" }, "state": { "$ref": "#/components/schemas/bulk_upload_state" }, "row_count": { "type": "integer", "description": "Total rows accepted after CSV validation.", "example": 100 }, "row_count_success": { "type": "integer", "description": "Rows that completed successfully.", "example": 97 }, "row_count_error": { "type": "integer", "description": "Rows that failed validation or processing.", "example": 3 }, "additional_settings": { "$ref": "#/components/schemas/bulk_upload_settings" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "updated_at": { "$ref": "#/components/schemas/datetime" }, "errors": { "type": "array", "description": "Upload-level validation or processing errors.", "items": { "$ref": "#/components/schemas/bulk_upload_error" } }, "original_file": { "$ref": "#/components/schemas/bulk_upload_file" }, "result_file": { "description": "Summary CSV of per-row outcomes (present when attached).", "$ref": "#/components/schemas/bulk_upload_file" }, "detailed_result_file": { "description": "Detailed XLSX export (present when attached).", "$ref": "#/components/schemas/bulk_upload_file" } }, "required": [ "id", "account_id", "product_configuration_id", "product_configuration_name", "state", "row_count", "row_count_success", "row_count_error", "additional_settings", "created_at", "updated_at", "errors" ], "example": { "id": "2b8313e8-b578-45a1-4efd-952b8313e890", "account_id": "1a7202d7-a467-34b0-3dec-841a7202d789", "product_configuration_id": "3c9424f9-c689-56b2-5f0e-a63c9424f901", "product_configuration_name": "county_criminal", "state": "processing", "row_count": 2, "row_count_success": 0, "row_count_error": 0, "additional_settings": { "lookback_period_in_years": 7 }, "created_at": "2026-08-05T12:00:00Z", "updated_at": "2026-08-05T12:00:05Z", "errors": [] } }, "bulk_upload_create_request": { "type": "object", "description": "Multipart form used to create a bulk upload.\n\n{% partial file=\"/_partials/bulk-upload-csv-formats.md\" /%}\n\nNested `settings` fields must be sent as form parts (for example\n`settings[lookback_period_in_years]=7`), not as a single JSON string part.\n", "properties": { "product_name": { "$ref": "#/components/schemas/bulk_upload_product_name" }, "original_file": { "type": "string", "format": "binary", "description": "CSV file (`.csv`). Max size is configured server-side." }, "settings": { "$ref": "#/components/schemas/bulk_upload_settings" } }, "required": [ "product_name", "original_file" ] }, "no_middle_name": { "type": "boolean", "default": false, "description": "Set to `true` to declare that the subject does not have a middle name.\n\n**Mutually exclusive with a non-empty `middle_name`:** the API rejects requests that\nsupply both a present `middle_name` and `no_middle_name: true`. An empty or null\n`middle_name` with `no_middle_name: true` is allowed. A non-empty `middle_name` may be\nsupplied with `no_middle_name: false`.\n\n**Allowed with `full_name`:** `full_name` and `no_middle_name` may be sent together.\nThat is not the same as supplying `middle_name` — when the flag is `true`, parsing\nstores only a first name and surname, and any token the parser would have treated as\na middle name is folded into the last name (for example `full_name: \"John Quincy Doe\"`\nbecomes first name `John` and last name `Quincy Doe`, with `middle_name` empty).\n\nSetting this to `true` clears a middle name already stored on a referenced profile.\nSupplying a non-empty `middle_name` without this field sets `no_middle_name` to `false`.\nWhen `true`, products that perform criminal-record identity matching exclude records\nwith a middle name, narrowing matches to subjects with no middle name on record.\nWhen supplied with `profile_id`, the value is persisted to the referenced profile\n(same account-scoped profile the check is created against).\nLeave as `false` (or omit) if unsure.\n" }, "masked_ssn_string": { "type": "string", "pattern": "^XXX-XX-\\d{4}$", "description": "A masked US Social Security Number showing only the last four digits.", "example": "XXX-XX-6789" }, "profile_fields": { "type": "object", "description": "Common fields used across profile-related schemas.", "properties": { "full_name": { "description": "The full name of the person. Must not be combined with first_name, middle_name, or last_name.\nMay be combined with `no_middle_name` on create/update; when that flag is `true`, parsing\nstores only a first name and surname (any middle token is folded into the last name).\n", "type": "string" }, "first_name": { "description": "The first name of the person.", "type": "string" }, "middle_name": { "description": "The middle name of the person. Can be null if not provided.", "type": "string" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "The last name of the person.", "type": "string" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "phone": { "description": "A phone number in the form +[country code][number including area code]. (E.164 format)\nA U.S. number supplied in national format (for example \"(415) 555-0123\") is normalized to\nE.164 on write. If invalid, the API returns a 400 with a `validation_error`.\n", "$ref": "#/components/schemas/phone_string" }, "country_code": { "description": "The phone country calling code supplied for a reverse phone verification (for example, \"1\" or \"54\").", "type": "string" }, "email": { "$ref": "#/components/schemas/email_string" }, "ssn": { "description": "US Social Security Number.\n\n**Masked by default** — API responses return `XXX-XX-{last4}`. Full SSN is\navailable via `?unmask_ssn=true` on endpoints that support it (driver checks and\nidentity verifications), subject to your account's product configuration. Contact\nyour account representative to enable SSN unmasking.\n\n**Always `null` on list/index endpoints** (e.g. `GET /profiles`, `GET /checks`), regardless\nof masking or unmasking settings. Fetch the individual resource (e.g. `GET /profiles/{id}`)\nto see the masked or unmasked value for a specific record.\n\nMay also be null on a single-resource response when no SSN was provided.\n", "oneOf": [ { "$ref": "#/components/schemas/ssn_string" }, { "$ref": "#/components/schemas/masked_ssn_string" }, { "type": "null" } ], "example": "XXX-XX-6789" }, "address": { "$ref": "#/components/schemas/address" }, "addresses": { "$ref": "#/components/schemas/addresses" }, "custom_id": { "$ref": "#/components/schemas/custom_id_string" }, "driver_license_state": { "$ref": "#/components/schemas/state_code" }, "driver_license_number": { "type": "string", "description": "The driver license number. Format dependent on State.", "example": "D1234567" } } }, "profile": { "title": "profile", "description": "A profile containing personal information used for checks and verifications.", "type": "object", "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/profile_id" } } }, { "$ref": "#/components/schemas/profile_fields" } ] }, "record_category": { "description": "A categorization of the type of record returned.\nMaps closely to the source category, except PA sources can contain either Patriot or Registry records.\n", "type": "string", "enum": [ "arrest", "Criminal/traffic", "Warrant", "Sex Offender", "Patriot", "Registry" ], "x-enumDescriptions": { "arrest": "arrest record (includes jail/prison records)", "Criminal/traffic": "criminal record (includes traffic records)", "Warrant": "warrant record", "Sex Offender": "sex offender list record", "Patriot": "watchlist records", "Registry": "registry records (not necessarily implying wrongdoing, so excluded by default)" }, "example": "Criminal/traffic" }, "record_match_confidence_level": { "description": "**Record match confidence** for this record: how strongly this record aligns with the identity it was matched\nto. Returned only for records sourced from Checkr's people data graph.\n\nThe values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.\n\n**Not comparable to other confidence fields.** This is measured independently from the case-level\n`identity_match_confidence_level` (below) and, on Profile Criminal Checks, from the profile-level\n`match_confidence_level`. The three answer different questions and are calibrated separately, so a **high**\non one does not mean the same thing as a **high** on another.\n\n**Absence:** Omitted when the record's source does not supply a match confidence.\n", "type": "string", "enum": [ "high", "medium", "low" ], "example": "high", "x-enumDescriptions": { "high": "Strong alignment between this record and the matched identity.", "medium": "Moderate alignment between this record and the matched identity.", "low": "Weak alignment between this record and the matched identity." } }, "source_category": { "description": "A categorization of the type of source where the data was retrieved.\nSome of the categories may not imply wrongdoing, and are excluded by default.\n", "type": "string", "enum": [ "arrest", "court", "criminal registry", "DOC", "warrant", "sex offender registry", "domestic watchlist", "foreign watchlist", "healthcare registry", "healthcare sanctions", "financial registry", "financial sanctions", "other registry", "other sanctions", "PEP registry" ], "x-enumDescriptions": { "arrest": "The source contains arrest records, typically from a sheriff's department or police department.", "court": "The source is a municipal, county, or state court, or administrative office of courts (AOC).", "criminal registry": "The source is a registry of violent or drug offenders", "DOC": "The source is a local police jail, or state prison (DOC means Department of Correction.)", "warrant": "The source is one which has requested the arrest of a person, typically a police department.", "sex offender registry": "The source is a registry of sex offenders. Typically at the state level.", "domestic watchlist": "The source is a US-based list of some sort of offender.", "foreign watchlist": "The source is a US-based list of some sort of offender, e.g. Interpol.", "healthcare registry": "The source is a list of medical professionals in some capacity, and does not imply wrongdoing. (Excluded by default.)", "healthcare sanctions": "The source is a list of medical professionals in some capacity, and implies wrongdoing.", "financial registry": "The source is a list of financial professionals in some capacity, and does not imply wrongdoing. (Excluded by default.)", "financial sanctions": "The source is a list of financial professionals in some capacity, and implies wrongdoing.", "other registry": "The source is a list of people, and does not imply wrongdoing. (Excluded by default.)", "other sanctions": "The source is a list of people, and implies wrongdoing.", "PEP registry": "The source is a list of politically exposed people (e.g. politicians and world leaders) who potentially could be bribed or coerced into wrongdoing. (Excluded by default.)" }, "example": "court" }, "source": { "type": "object", "properties": { "id": { "description": "An identifier for the source. E.g. \"cookil\" or \"NJ_Supreme_Ct_view\". Can be used to programmatically exclude a source.", "type": "string", "example": "ARSTfranklinKY" }, "category": { "$ref": "#/components/schemas/source_category", "example": "arrest" }, "name": { "description": "A human-understandable (English) name of the source.", "type": "string", "example": "KY Franklin County Inmates" }, "county": { "description": "The name of the county (if any) where the record came from.", "type": "string", "example": "Franklin" }, "county_fips_code": { "description": "The 5-digit FIPS code of the county where the record came from.\nPresent for county checks; omitted for sources without an associated county.\n", "type": "string", "example": "17031" }, "state": { "$ref": "#/components/schemas/state_code" } } }, "record_core": { "type": "object", "properties": { "record_id": { "description": "A stable identifier for this record, derived from the record content.\nFormat: `record-{sha256_hash}`.\nThis ID is globally unique across all checks and can be referenced\nin adverse action requests to identify disqualifying records.\n", "type": "string", "example": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "category": { "$ref": "#/components/schemas/record_category" }, "record_match_confidence_level": { "$ref": "#/components/schemas/record_match_confidence_level" }, "person": { "description": "Person attributes as reported on this record. Only fields that have a value are returned;\nmost records include only a subset of these fields.\n", "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "middle_name": { "description": "middle initial or name or names", "type": "string", "example": "W" }, "last_name": { "type": "string", "example": "Smith" }, "suffix": { "type": "string" }, "full_name": { "type": "string", "example": "Smith, John W." }, "dob": { "$ref": "#/components/schemas/date_string_partial" }, "last_collected_date": { "description": "The date the provider last collected or observed this record. This person-level field is\nreturned only for check-family products when `include_last_collected_date` is enabled on\nthe product configuration. It is distinct from the Checkr-calculated `record_date` on an\nindividual charge.\n", "$ref": "#/components/schemas/date_string_complete" }, "inferred_dob": { "description": "Some records which do not already have a full DOB may have an inferred full DOB that was found by other means.\nFor example a record may have no dob, or only a partial dob, but we were able to inferred a full dob using other similar records.\n", "$ref": "#/components/schemas/date_string_complete" }, "doc_number": { "description": "Dept. of Corrections number.\nA number or identifier given by a state Dept. of Corrections to identify a person who went to prison.\n", "type": "string" }, "gender": { "description": "The gender, if any, as recorded by the source. No specific format.", "type": "string", "example": "M" }, "height": { "description": "The height, if any, as recorded by the source. No specific format.", "type": "string", "example": "601" }, "weight": { "description": "The weight, if any, as recorded by the source. No specific format.", "type": "string", "example": "180" }, "hair_color": { "description": "The hair color, if any, as recorded by the source. No specific format.", "type": "string", "example": "BRN" }, "eye_color": { "description": "The eye color if any, as recorded by the source. No specific format.", "type": "string", "example": "HAZ" }, "skin_color": { "description": "The skin color, if any, as recorded by the source. No specific format.", "type": "string", "example": "wht" }, "race": { "description": "The race as defined by the source. No specific format.", "type": "string", "example": "W" }, "ethnicity": { "description": "The ethnicity, if any, as recorded by the source. No specific format.", "type": "string", "example": "Hispanic-American" }, "physical_build": { "description": "The physical build, if any, as recorded by the source. No specific format.", "type": "string", "example": "BROAD" }, "physical_marks": { "description": "Scars, marks, and tattoos as defined by the source. No specific format.", "type": "string", "example": "blue cross on outside left ankle" }, "photo_urls": { "description": "A set of URLs referencing pictures of this person, as recorded by the source.", "type": "array", "items": { "description": "A public URL which has an image, as recorded by the source.\nSometimes, the picture is an image which shows the text \"No Image Available.\"\nWe are working on removing those, but you may still encounter them.\n", "type": "string", "format": "uri" } }, "name_aliases": { "description": "Other names that this person may have gone by.", "type": "array", "items": { "type": "string", "example": "Johnny Smith" } }, "dob_aliases": { "description": "Other dates of birth that this person may have used.", "type": "array", "items": { "type": "string", "example": "19940321" } }, "addresses": { "description": "Addresses associated with this person on this record, as reported by the data source.\nOmitted when the source provides no address information. Each entry may be partial.\n", "type": "array", "items": { "$ref": "#/components/schemas/address_as_reported" }, "example": [ { "street": "123 Main St", "city": "Frankfort", "state": "KY", "zip_code": "40601" }, { "street": "OFFENDER REPORTS MOVED OUT OF UTAH" } ] } } }, "source": { "$ref": "#/components/schemas/source" } } }, "case_core": { "type": "object", "properties": { "case_id": { "description": "A stable identifier for this case, derived from the case content.\nFormat: `case-{sha256_hash}`.\n", "type": "string", "example": "case-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "case_number": { "description": "The case number assigned by a court. Not present for records which are not from a court. Format varies.", "type": "string", "example": "2025-99999" }, "type": { "description": "The case type as reported by the court. Not present for records which are not from a court. Format varies.", "type": "string" }, "status": { "description": "The case status as reported by the court. Sparsely available. Format varies.", "type": "string" }, "file_date": { "description": "The date the case was filed as reported by the court. Not present for records which are not from a court.", "$ref": "#/components/schemas/date_string_partial" }, "arresting_agency": { "description": "The name of the arresting agency.", "type": "string", "example": "Franklin County Sheriff" }, "arrest_date": { "description": "The date the person was arrested.", "$ref": "#/components/schemas/date_string_partial" }, "court_name": { "description": "The name of the charging court.", "type": "string", "example": "Franklin County Circuit Court" }, "court_county": { "description": "The county of the charging court.", "type": "string", "example": "Franklin" } } }, "identity_match_confidence_level": { "description": "**Identity match confidence** for this case. When present, it indicates how strongly this criminal case aligns\nwith the PII you submitted for the check.\n\nDistinct from the record-level `record_match_confidence_level`: this field is about a single **case** versus the\nPII you submitted, while that one is about a whole **record** versus the identity it was matched to. They are\nmeasured separately and should not be compared to each other.\n\nThe values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.\n\n**Other values:** **unknown** — identity matching was enabled for the check but a confidence label could not be determined for this case. **insufficient_information** — identity matching was skipped (for example, insufficient identifiers); check `run_notes` for context.\n\n**Absence:** Omitted when identity matching was not enabled for the check. Reach out to support@checkrtrust.com if you are interested in enabling this feature\n", "type": "string", "enum": [ "high", "medium", "low", "unknown", "insufficient_information" ], "example": "high", "x-enumDescriptions": { "high": "Strong identity alignment with the searched subject.", "medium": "Moderate alignment with the searched subject.", "low": "Weak alignment with the searched subject.", "unknown": "Identity matching was on, but no confidence label was available for this case.", "insufficient_information": "Identity matching did not run for this check (often due to insufficient PII)." } }, "charge_type": { "description": "the type (level, severity) of a charge", "type": "string", "title": "category", "enum": [ "felony", "misdemeanor", "petty_offense", "unknown" ], "example": "petty_offense" }, "charge_category": { "description": "the highest level of categorization of a charge", "type": "string", "title": "category", "enum": [ "Criminal Intent", "Drugs & Alcohol", "Fraud & Deception", "Homicide", "Security", "Sexual", "Statutory", "Theft & Property", "Vehicles & Traffic", "Violence", "unclassified" ], "example": "Theft & Property" }, "charge_subcategory": { "description": "the second level of categorization of a charge", "type": "string", "title": "subcategory", "enum": [ "Accessory", "Conspiracy", "Court Orders", "Criminal Tools", "Obstruction", "Organized Crime", "Alcohol & Tobacco", "Driving under the Influence (DUI)", "Drugs-Marijuana Possession/Use", "Drugs-Possession/Use", "Drugs-Sale & Manufacture", "Bribery & Corruption", "Business & Tax", "Cyber Crimes", "Embezzlement", "Forgery", "Fraud", "Identity Theft & Impersonation", "Worthless Check", "Attempted Homicide", "Intentional Homicide", "Unintentional Killing", "Immigration", "Terrorism", "Treason", "Lewd Behavior", "Prostitution", "Sexual Abuse", "Animal Ordinances", "Custody & Support", "Fish & Game", "Gambling", "Miscellaneous Citations & Violations", "Public Nuisance", "Safety & Zoning", "Arson", "Burglary", "Petty Theft", "Possession of Stolen Property", "Robbery", "Theft", "Trespassing", "Vandalism & Mischief", "License & Registration", "Parking", "Speeding", "Unsafe Operation", "Vehicle Equipment", "Abduction & Restraint", "Animal Cruelty", "Assault & Battery", "Child & Elder Abuse", "Disorderly Behavior", "Harassment & Threats", "Weapons & Endangerment", "unclassified" ], "example": "Petty Theft" }, "charge_subsubcategory": { "description": "The lowest (most detailed) level of categorization of a charge.\nThere are over 250 of these.\nThey are one of the categorizations on which rulesets operate.\n", "type": "string", "title": "subsubcategory", "example": "Retail Theft" }, "sentence": { "type": "object", "properties": { "conviction_date": { "$ref": "#/components/schemas/date_string_partial" }, "begin_date": { "description": "Date the sentence began, if reported.", "$ref": "#/components/schemas/date_string_partial" }, "actual_release_date": { "description": "Date the person was actually released, if reported.", "$ref": "#/components/schemas/date_string_partial" }, "scheduled_release_date": { "description": "Scheduled release date, if reported.", "$ref": "#/components/schemas/date_string_partial" }, "release_type": { "description": "Type of release, if reported.", "type": "string" }, "details": { "description": "Description of the sentence, if any", "type": "string", "example": "fine, 1D" } } }, "disposition_type": { "description": "the type of disposition", "type": "string", "enum": [ "Conviction", "Dismissed", "Invalid", "Merged", "Pending", "Transferred", "Warrant", "Unclassified" ], "example": "Conviction" }, "disposition": { "type": "object", "properties": { "disposition": { "description": "A description of the disposition, as provided by the court, if any.", "type": "string", "example": "GLT" }, "disposition_date": { "$ref": "#/components/schemas/date_string_partial" }, "disposition_type": { "$ref": "#/components/schemas/disposition_type" } } }, "charge": { "type": "object", "properties": { "charge_id": { "description": "A stable identifier for this charge, derived from the charge content.\nFormat: `charge-{sha256_hash}`.\n", "type": "string", "example": "charge-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "description": { "description": "The description of the offense, as reported on the record. Format varies.", "type": "string", "example": "SHOPLIFTING" }, "offense_date": { "description": "The date the offense was committed, as reported on the record.", "$ref": "#/components/schemas/date_string_partial" }, "legal_code": { "description": "Legal code (statute) as reported by the court or arresting agency.", "type": "string", "example": "433.234" }, "type": { "$ref": "#/components/schemas/charge_type" }, "category": { "$ref": "#/components/schemas/charge_category" }, "subcategory": { "$ref": "#/components/schemas/charge_subcategory" }, "subsubcategory": { "$ref": "#/components/schemas/charge_subsubcategory" }, "record_date": { "description": "Date of the record.\nThis is not part of the record itself.\nIt is a field calculated by Checkr.\nIt is the field used to determine if the charge is within the lookback period.\nAlthough there are many other situations, often a convicted charge has a\nrecord_date which is the disposition_date, and a non-conviction charge\nhas a record_date which is the filing date.\n", "$ref": "#/components/schemas/date_string_partial" }, "city": { "description": "The name of the city where the person was charged", "type": "string", "example": "Indian Hills" }, "county": { "description": "The name of the county where the person was charged", "type": "string", "example": "Jefferson" }, "state": { "description": "The state where the person was charged", "type": "string", "example": "KY" }, "sentences": { "type": "array", "items": { "$ref": "#/components/schemas/sentence" } }, "dispositions": { "type": "array", "items": { "$ref": "#/components/schemas/disposition" } } } }, "case": { "allOf": [ { "$ref": "#/components/schemas/case_core" }, { "type": "object", "properties": { "identity_match_confidence_level": { "$ref": "#/components/schemas/identity_match_confidence_level" }, "charges": { "description": "Only fields that have a value are returned. Most charges will have only a subset of these fields.", "type": "array", "items": { "$ref": "#/components/schemas/charge" } } } } ] }, "record": { "title": "record", "allOf": [ { "$ref": "#/components/schemas/record_core" }, { "type": "object", "properties": { "cases": { "description": "Only fields that have a value are returned. Most cases will have only a subset of these fields.", "type": "array", "items": { "$ref": "#/components/schemas/case" } } } } ] }, "check_type": { "type": "string", "enum": [ "instant_criminal", "sex_offender_registry" ] }, "check": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "description": "Timestamp when the check completed and results became available.\n`null` while the check is still pending.\n", "oneOf": [ { "$ref": "#/components/schemas/datetime" }, { "type": "null" } ] }, "results": { "description": "Array of criminal **records**. When no records are found, this is an empty array.\n\n**Confidence scoring:** Each record's `cases[]` entries may include `identity_match_confidence_level`,\nsummarizing identity-match confidence for that case. See the `case` schema and the Instant Criminal Checks tag description.\n", "type": "array", "items": { "$ref": "#/components/schemas/record" } }, "check_type": { "$ref": "#/components/schemas/check_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "run_notes": { "description": "An unstructured array of human-readable notes about this particular check.\nMay contain notes about how input was parsed,\nor other information about results.\nNot intended to be parsed by computer, as these notes are not guaranteed to be in any given format.\n", "type": "array", "items": { "type": "string", "example": "changed last_name from 'Smith Jr' to 'Smith'" } }, "results_found": { "description": "Present only when `include[]=results_found` is requested; omitted otherwise.\nWhen present, the `results` array is omitted.\n", "type": "boolean" }, "rulesets_applied": { "description": "Present only when `include[]=rulesets_applied` is requested; omitted otherwise.", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_applied" } } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "check with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "check with profile object" } ] }, "name_full_or_split_required": { "type": "object", "description": "Exactly one name format must be provided: either `full_name` alone, or `first_name` and\n`last_name` (optionally with `middle_name`). Combining `full_name` with a name-part field\n(`first_name`, `middle_name`, or `last_name`) is rejected. `no_middle_name` may be sent\nalongside either format.\n", "allOf": [ { "not": { "allOf": [ { "not": { "required": [ "full_name" ] } }, { "not": { "required": [ "first_name", "last_name" ] } } ] } }, { "not": { "anyOf": [ { "required": [ "full_name", "first_name" ] }, { "required": [ "full_name", "middle_name" ] }, { "required": [ "full_name", "last_name" ] } ] } } ] }, "middle_name_no_middle_name_exclusive": { "type": "object", "description": "Rejects a non-empty `middle_name` combined with `no_middle_name: true`.\nMatches runtime validation (`middle_name` must be present/non-blank to conflict).\nEmpty or null `middle_name` with `no_middle_name: true` is allowed.\n`full_name` is not covered here — it may be combined with `no_middle_name` (see\nthe shared `no_middle_name` schema).\n", "properties": { "middle_name": { "type": "string" }, "no_middle_name": { "type": "boolean" } }, "not": { "required": [ "middle_name", "no_middle_name" ], "properties": { "middle_name": { "type": "string", "minLength": 1 }, "no_middle_name": { "enum": [ true ] } } } }, "check_request_allow_duplicate_criminal_records": { "type": "boolean", "default": false, "description": "**Multi-source deduplication** runs by default for instant criminal, targeted instant criminal,\nsex offender registry, and `criminal_check` (via `POST /v1/criminal_checks`). It may merge or\nsuppress duplicate rows across data providers.\n\n- **`false` or omit:** apply deduplication for this check.\n- **`true`:** skip multi-source deduplication; results may include duplicate source rows in storage\n and in API responses (and webhooks for `criminal_check`).\n\n**Create-time only:** send on create; not a query parameter on `GET`.\n" }, "check-request-from-pii": { "type": "object", "properties": { "check_type": { "$ref": "#/components/schemas/check_type" }, "input_type": { "$ref": "#/components/schemas/input_type" }, "first_name": { "description": "first name (given name). Do not include prefixes, like \"Ms.\" or \"Dr.\"", "type": "string", "example": "Jane" }, "middle_name": { "description": "middle name(s)", "type": "string", "example": "Mary Louise" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "last name (surname). Do not include suffixes, like \"Jr.\" or \"2nd\".", "type": "string", "example": "O'Donnell-Van Helsing" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name,\nand then use those for the check. With `no_middle_name: true`, any parsed middle token is folded\ninto the last name instead of being stored as a middle name.\nIf you already know the first and last names, we suggest sending them.\nThe parser will attempt to remove prefixes and suffixes, and handles several different formats of name,\nbut we cannot guarantee it will parse the name in the manner you expect.\n", "type": "string", "example": "O'Donnell-Van Helsing, Dr. Jane Mary Louise, MD" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "description": "Social Security Number used for additional identity verification and record matching", "$ref": "#/components/schemas/ssn_string" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "addresses": { "description": "{% partial file=\"/_partials/schema-check-addresses-field-criminal-search.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" }, "order_by": { "$ref": "#/components/schemas/order_by" }, "allow_duplicate_criminal_records": { "$ref": "#/components/schemas/check_request_allow_duplicate_criminal_records" } }, "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "JOHN", "last_name": "SMITH", "dob": "19900101", "ssn": "123-45-6789", "phone": "+14155552671", "addresses": [ { "street": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip_code": "90001" }, { "street": "789 Pine Blvd", "city": "San Diego", "state": "CA", "zip_code": "92101" } ] } }, "check_type_sex_offender_registry": { "type": "string", "title": "check_type", "enum": [ "sex_offender_registry" ] }, "address_request": { "description": "An address to be searched for records.\n- In searching by address, records are matched by street number, street name, city, and state\n- Unit/apartment numbers are not used for matching addresses\n- Street types (Avenue, Street, Boulevard) are not used for matching addresses\n- For example, \"123 Main St., Apt. 3B\" will match using \"123\" and \"Main\"\n", "allOf": [ { "$ref": "#/components/schemas/address" } ] }, "check-request-from-address": { "description": "the request to create a new check using an address", "properties": { "check_type": { "$ref": "#/components/schemas/check_type_sex_offender_registry" }, "input_type": { "$ref": "#/components/schemas/input_type_address" }, "address": { "$ref": "#/components/schemas/address_request", "description": "{% partial file=\"/_partials/schema-inline-address-persistence-singular-or-plural.md\" /%}\n" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" }, "order_by": { "$ref": "#/components/schemas/order_by" }, "allow_duplicate_criminal_records": { "$ref": "#/components/schemas/check_request_allow_duplicate_criminal_records" } }, "required": [ "check_type", "input_type", "address" ], "example": { "check_type": "sex_offender_registry", "input_type": "address", "address": { "street": "123 Main Street", "city": "New York", "state": "NY", "zip_code": "12345" } } }, "check-request-from-profile": { "description": "Create a check from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request`.\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "properties": { "check_type": { "$ref": "#/components/schemas/check_type" }, "input_type": { "$ref": "#/components/schemas/input_type" }, "profile_id": { "$ref": "#/components/schemas/profile_id" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "source_states": { "$ref": "#/components/schemas/source_states" }, "order_by": { "$ref": "#/components/schemas/order_by" }, "allow_duplicate_criminal_records": { "$ref": "#/components/schemas/check_request_allow_duplicate_criminal_records" } }, "required": [ "profile_id" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080" } }, "check_type_driver_license_status": { "type": "string", "enum": [ "driver_license_status" ] }, "driver_check_driver_license_status_result": { "title": "driver_license_status_result", "type": "object", "properties": { "requested_profile": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/profile_fields" } ], "description": "The inputs used to create the driver check. Fields that weren't provided will not be included." }, "passenger": { "type": "object", "properties": { "validity": { "type": "string", "enum": [ "VALID", "INVALID", "NOT FOUND" ], "x-enumDescriptions": { "VALID": "The license number is valid and reflects the authorization to drive a passenger vehicle.", "INVALID": "The license number is invalid and cannot be used to drive a passenger vehicle.", "NOT FOUND": "We did not find a definitive result for this license. This could indicate the 'requested_profile' values had an error / typo. Another possibility is that we were unable to determine the 'ssn' and/or 'zip_code' fields, they are required for the requested state, and they weren't provided in the requested_profile." } } } } } }, "driver_check_driver_license_status": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "description": "A datetime, or null if not completed.", "oneOf": [ { "$ref": "#/components/schemas/datetime" }, { "type": "null" } ] }, "results": { "description": "Results, or null if not completed.", "oneOf": [ { "$ref": "#/components/schemas/driver_check_driver_license_status_result" }, { "type": "null" } ] }, "check_type": { "$ref": "#/components/schemas/check_type_driver_license_status" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "check_type": { "$ref": "#/components/schemas/check_type_driver_license_status" } }, "title": "driver license status with profile id", "required": [ "profile_id" ] }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" }, "check_type": { "$ref": "#/components/schemas/check_type_driver_license_status" } }, "title": "driver license status with profile object", "required": [ "profile" ] } ] }, "check_type_motor_vehicle_report": { "type": "string", "enum": [ "motor_vehicle_report" ] }, "driver_check_result_code": { "type": "string", "title": "result_code", "enum": [ "FOUND", "NOT FOUND", "REJECTED", "LOCKED" ], "x-enumDescriptions": { "FOUND": "motor vehicle report yielded results", "NOT FOUND": "motor vehicle report information yielded no results", "REJECTED": "motor vehicle report information was invalid or an unknown error occurred", "LOCKED": "the motor vehicle report is not available electronically" } }, "driver_event": { "title": "driver_event", "type": "object", "properties": { "description": { "type": "string", "description": "A description of the event" }, "code": { "type": "string", "description": "Normalized code for this type of event" }, "acd_code": { "type": "string", "description": "Normalized AAMVA Code Dictionary (ACD) code for this event" }, "type": { "type": "string", "description": "The type of event (conviction, suspension, etc.)" }, "jurisdiction": { "type": "string", "description": "The jurisdiction the event took place in" }, "location": { "type": "string", "description": "A more specific location of the event (if provided)" }, "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date the event occurred" }, "disposition_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date the disposition took effect (if provided)" }, "disposition": { "type": "string", "description": "The current status or final outcome of the event" }, "points": { "type": "string", "description": "(Jurisdiction-specific) the number of points affected, added, etc." }, "additional_detail": { "type": "string", "description": "Additional detail about the event normally pertaining to speed such as the speed the vehicle was traveling, how fast it was going above the speed limit, whether or not the vehicle was traveling over 100 MPH, etc." } } }, "driver_crash": { "title": "driver_crash", "type": "object", "properties": { "date": { "$ref": "#/components/schemas/date", "description": "The date the crash occurred" }, "type": { "type": "string", "description": "The type of crash" }, "jurisdiction": { "type": "string", "description": "The jurisdiction where the crash occurred." }, "location": { "type": "string", "description": "A more specific location of the crash (if provided)" }, "description": { "type": "string", "description": "A description of the crash" }, "severity": { "type": "string", "enum": [ "AC0", "AC1", "AC2", "AC3", "NEW" ], "x-enumDescriptions": { "AC0": "Undeclared", "AC1": "Property Damage", "AC2": "Injury", "AC3": "Fatality", "NEW": "Unassigned" } }, "was_citation_issued": { "type": "boolean", "description": "Whether or not a citation was issued for this crash" }, "comments": { "type": "array", "description": "Information related to the section that could not be associated with a named field", "items": { "type": "string" } } } }, "driver_jurisdiction_action": { "title": "jurisdiction_action", "type": "object", "properties": { "type": { "type": "string", "description": "The type of action taken (i.e. suspension, revocation, withdrawal, etc.)" }, "group": { "description": "Removal of Driving Privileges (RDP) Group. This provides additional context as to why an action was taken.", "type": "string", "pattern": "^RDP[0-9]{2}$", "enum": [ "RDP00", "RDP01", "RDP10", "RDP11", "RDP20", "RDP30", "RDP31", "RDP32", "RDP33", "RDP40", "RDP50", "RDP60", "RDP70", "RDP71" ], "x-enumDescriptions": { "RDP00": "Unspecified", "RDP01": "Unassignable", "RDP10": "Alcohol or Drug Influence", "RDP11": "Alcohol or Drug Related (Non-Driving)", "RDP20": "Cumulative (too many violations)", "RDP30": "Other Actions (Unlicensed, Reckless, Hit & Run, etc.)", "RDP31": "Driving While Barred", "RDP32": "Reckless Driving", "RDP33": "Vehicle Use in Prohibited Offenses", "RDP40": "Failure to Pay / Failure to Appear", "RDP50": "Financial Responsibilty (no insurance at time of crash, cancellation of insurance, etc.)", "RDP60": "Non-DMV-Related", "RDP70": "DMV-Related", "RDP71": "CDL Downgrade" } }, "start_date": { "description": "The date the action became effective", "$ref": "#/components/schemas/date" }, "end_date": { "description": "The date the action is no longer effective", "$ref": "#/components/schemas/date" }, "extent_of_action": { "description": "The extent of what privileges are affected by this action", "type": "string" }, "description": { "description": "A description of the action", "type": "string" }, "initiating_jurisdiction": { "description": "The jurisdiction that took or initiated this action", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "comments": { "description": "Information related to the section that could not be associated with a named field.", "type": "array", "items": { "type": "string" } } } }, "driver_license_type": { "description": "If the license type is PREVIOUS or OUT OF STATE, the rest of the license information may not be present.", "type": "string", "title": "type", "enum": [ "CDL", "CDL PERMIT", "MOTORCYCLE", "MOTORCYCLE PERMIT", "PASSENGER", "PASSENGER PERMIT", "MOPED", "ID CARD", "PREVIOUS", "OUT OF STATE" ], "example": "PASSENGER" }, "driver_license_validity": { "type": "string", "title": "validity", "enum": [ "VALID", "INVALID", "UNKNOWN" ], "example": "VALID" }, "driver_license_license_dls": { "title": "license", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/driver_license_type" }, "validity": { "$ref": "#/components/schemas/driver_license_validity" }, "jurisdiction": { "description": "The jurisdiction that issued the license", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "number": { "description": "The license number. Format dependent on State.", "type": "string" }, "class_code": { "description": "Code representing the license class (may not have a value if class_description is provided)", "type": "string" }, "class_description": { "description": "Description of the license class (may not have a value if class_code is provided)", "type": "string" }, "status_code": { "description": "Code representing the license status (may not have a value if status_description is provided)", "type": "string" }, "status_description": { "description": "Description of the license status (may not have a value if status_code is provided)", "type": "string" }, "issued_on": { "$ref": "#/components/schemas/datetime", "description": "The date the license was issued (may or may not be present)" }, "expires_on": { "$ref": "#/components/schemas/datetime", "description": "The date the license expires\n\nNote: the following jurisdictions do not provide this information:\n- Hawaii (HI)\n" } } }, "driver_license_restriction": { "title": "restriction", "type": "object", "properties": { "code": { "description": "Code for the restriction", "type": "string" }, "description": { "description": "Description of the restriction", "type": "string" }, "category": { "description": "The category of restriction", "type": "string" } } }, "driver_license_endorsement": { "title": "endorsement", "type": "object", "properties": { "code": { "description": "Code for the endorsement", "type": "string" }, "description": { "description": "Description of the endorsement", "type": "string" }, "category": { "description": "The category of endorsement", "type": "string" } } }, "driver_license_license_mvr": { "title": "license", "type": "object", "allOf": [ { "$ref": "#/components/schemas/driver_license_license_dls" }, { "type": "object", "properties": { "restrictions": { "description": "Restrictions that apply to the license (must wear corrective lenses, cannot operate a certain type of vehicle, etc.)", "type": "array", "items": { "$ref": "#/components/schemas/driver_license_restriction" } }, "endorsements": { "description": "Endorsements applied to the license (can drive school buses, drive HAZMAT vehicles, drive truck with double or triple trailers, etc.)", "type": "array", "items": { "$ref": "#/components/schemas/driver_license_endorsement" } }, "comments": { "description": "Information related to the section that could not be associated with a named field", "type": "array", "items": { "type": "string" } } } } ] }, "driver_license_miscellaneous": { "title": "miscellaneous", "type": "object", "properties": { "date": { "description": "A date associated with this miscellaneous information (if provided)", "$ref": "#/components/schemas/date" }, "description": { "description": "A description of the miscellaneous information", "type": "string" }, "comments": { "description": "Information related to the section that could not be associated with a named field", "type": "array", "items": { "type": "string" } } } }, "driver_check_motor_vehicle_report_result": { "title": "motor_vehicle_report_result", "type": "object", "properties": { "order_details": { "description": "Order metadata", "type": "object", "properties": { "result_code": { "$ref": "#/components/schemas/driver_check_result_code" } } }, "driver_information": { "description": "Information regarding the driver's PII", "type": "object", "properties": { "date_of_birth": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The driver's date of birth\n\nNote: the following jurisdictions do not provide this information:\n- Georgia (GA)\n- Illinois (IL)\n- New Jersey (NJ)\n" }, "license": { "description": "License information", "type": "object", "properties": { "number": { "type": "string", "description": "The license number" }, "jurisdiction": { "type": "string", "description": "The jurisdiction that issued the license" } } }, "name": { "description": "The driver's name broken into separate fields", "type": "object", "properties": { "first": { "type": "string", "description": "The driver's first name" }, "middle": { "type": "string", "description": "The driver's middle name" }, "last": { "type": "string", "description": "The driver's last name" }, "suffix": { "type": "string", "description": "The driver's name suffix" }, "raw": { "type": "string", "description": "The driver's full name as received" } } } } }, "driver_events": { "description": "Events on a driver's record (convictions, violations, citations, abstracts, etc.)", "type": "array", "items": { "$ref": "#/components/schemas/driver_event" } }, "crashes": { "description": "Crashes on a driver's record", "type": "array", "items": { "$ref": "#/components/schemas/driver_crash" } }, "jurisdiction_actions": { "description": "Actions taken by a jurisdiction on or against a driver (suspensions, revocations, withdrawals, etc.)", "type": "array", "items": { "$ref": "#/components/schemas/driver_jurisdiction_action" } }, "licenses": { "description": "Licenses associated with the driver", "type": "array", "items": { "$ref": "#/components/schemas/driver_license_license_mvr" } }, "miscellaneous": { "description": "Miscellaneous information that could not be categorized into permanent data attributes", "type": "array", "items": { "$ref": "#/components/schemas/driver_license_miscellaneous" } } } }, "driver_check_motor_vehicle_report": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "description": "A datetime, or null if not completed.", "oneOf": [ { "$ref": "#/components/schemas/datetime" }, { "type": "null" } ] }, "results": { "description": "Results, or null if not completed.", "oneOf": [ { "$ref": "#/components/schemas/driver_check_motor_vehicle_report_result" }, { "type": "null" } ] }, "profile_id": { "$ref": "#/components/schemas/profile_id" }, "profile": { "$ref": "#/components/schemas/profile" }, "check_type": { "$ref": "#/components/schemas/check_type_motor_vehicle_report" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "check_type": { "$ref": "#/components/schemas/check_type_motor_vehicle_report" } }, "title": "motor vehicle report with profile id", "required": [ "profile_id", "check_type" ] }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" }, "check_type": { "$ref": "#/components/schemas/check_type_motor_vehicle_report" } }, "title": "motor vehicle report with profile object", "required": [ "profile" ] } ] }, "driver_check_type": { "type": "string", "title": "check_type", "enum": [ "driver_license_status", "motor_vehicle_report" ] }, "driver-check-request-from-pii": { "type": "object", "description": "Create a driver check by providing PII directly.", "properties": { "first_name": { "type": "string", "description": "First name of the person. Required (with last_name) when not sending full_name." }, "last_name": { "type": "string", "description": "Last name of the person. Required (with first_name) when not sending full_name." }, "full_name": { "type": "string", "description": "Either send the full name, or first and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nIf you already know the first and last names, we suggest sending them.\n", "example": "Jane Doe" }, "dob": { "$ref": "#/components/schemas/date", "description": "Date of birth (ISO 8601 date string).\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n" }, "driver_license_number": { "type": "string", "description": "Driver license number" }, "driver_license_state": { "$ref": "#/components/schemas/state_code", "description": "State that issued the driver license" }, "check_type": { "$ref": "#/components/schemas/driver_check_type" }, "zip_code": { "$ref": "#/components/schemas/zip_code", "description": "{% partial file=\"/_partials/schema-driver-check-zip-code-field.md\" /%}\n" }, "address": { "$ref": "#/components/schemas/address", "description": "{% partial file=\"/_partials/schema-driver-check-address-field.md\" /%}\n" }, "addresses": { "description": "{% partial file=\"/_partials/schema-driver-check-addresses-field.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "required": [ "driver_license_number", "driver_license_state", "check_type" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" } ], "example": { "first_name": "Jane", "last_name": "Doe", "dob": "1990-01-15", "driver_license_number": "12345678", "driver_license_state": "TX", "check_type": "motor_vehicle_report", "addresses": [ { "street": "123 Main St", "city": "Austin", "state": "TX", "zip_code": "78701", "country": "US" } ] } }, "driver-check-request-from-profile": { "type": "object", "description": "Create a driver check from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request`.\n", "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "check_type": { "$ref": "#/components/schemas/driver_check_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "required": [ "profile_id", "check_type" ] }, "driver_check": { "oneOf": [ { "$ref": "#/components/schemas/driver_check_driver_license_status" }, { "$ref": "#/components/schemas/driver_check_motor_vehicle_report" } ] }, "driver-license-status-completed-event-body": { "type": "object", "description": "Emitted when a driver license status check completes. The embedded `data.profile.ssn`\nis included in masked form (`XXX-XX-{last4}`) only. To retrieve the full SSN, call\n`GET /v1/driver_checks/{driver_check_id}?unmask_ssn=true`; the unmasked value appears\nin `results.requested_profile.ssn` (or `results_v2.requested_profile.ssn`), not in\n`profile.ssn`.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "driver_license_status.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "$ref": "#/components/schemas/driver_check_driver_license_status_result" }, "profile": { "description": "The profile associated with this check. `ssn` is included in masked form (`XXX-XX-{last4}`) only.", "$ref": "#/components/schemas/profile" }, "check_type": { "$ref": "#/components/schemas/check_type_driver_license_status" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } } }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "motor-vehicle-report-completed-event-body": { "type": "object", "description": "Emitted when a motor vehicle report check completes. The embedded `data.profile.ssn`\nis included in masked form (`XXX-XX-{last4}`) only. To retrieve the full SSN, call\n`GET /v1/driver_checks/{driver_check_id}?unmask_ssn=true`; the unmasked value appears\nin `results.requested_profile.ssn`, not in `profile.ssn`.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "motor_vehicle_report.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "$ref": "#/components/schemas/driver_check_motor_vehicle_report_result" }, "profile": { "description": "The profile associated with this check. `ssn` is included in masked form (`XXX-XX-{last4}`) only.", "$ref": "#/components/schemas/profile" }, "check_type": { "$ref": "#/components/schemas/check_type_motor_vehicle_report" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } } }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "attribute_match_score": { "description": "0 if an attribute does not match, 100 if it matches", "type": "integer", "enum": [ 0, 100 ] }, "attribute_match_scores": { "description": "attribute match scores", "type": "object", "properties": { "first_name": { "$ref": "#/components/schemas/attribute_match_score" }, "last_name": { "$ref": "#/components/schemas/attribute_match_score" }, "dob": { "$ref": "#/components/schemas/attribute_match_score" }, "phone": { "$ref": "#/components/schemas/attribute_match_score" }, "email": { "$ref": "#/components/schemas/attribute_match_score" }, "address": { "$ref": "#/components/schemas/attribute_match_score" }, "city": { "$ref": "#/components/schemas/attribute_match_score" }, "state": { "$ref": "#/components/schemas/attribute_match_score" }, "zip_code": { "$ref": "#/components/schemas/attribute_match_score" }, "ssn": { "$ref": "#/components/schemas/attribute_match_score" } }, "example": { "first_name": 100, "last_name": 100, "dob": 100, "phone": 100, "email": 0, "address": 100, "city": 100, "state": 100, "zip_code": 100, "ssn": 0 } }, "attribute_match_score_overall": { "description": "0 if no attributes match, 50 if some attributes match, 100 if all attributes match", "type": "integer", "enum": [ 0, 50, 100 ], "example": 50 }, "idv_result_context_item": { "title": "idv_result_context_item", "type": "object", "properties": { "code": { "type": "string", "description": "A stable code for the reason or context", "example": "CT-0195" }, "title": { "type": "string", "description": "A user-friendly description of the reason or context", "example": "Address is correlated with a past address" }, "category": { "type": "string", "description": "Category derived from the provider reason code.", "enum": [ "informational", "rejection", "unknown" ], "example": "informational" } } }, "idv_result_pii_validation": { "title": "idv_result_pii_validation", "type": "object", "properties": { "attribute_match_scores": { "$ref": "#/components/schemas/attribute_match_scores" }, "overall_match_score": { "$ref": "#/components/schemas/attribute_match_score_overall" }, "result_context": { "type": "array", "items": { "$ref": "#/components/schemas/idv_result_context_item" } } } }, "idv_collection_link": { "title": "idv_collection_link", "type": "object", "properties": { "url": { "description": "URL for the document collection application.", "type": "string", "format": "uri" }, "qr_code": { "description": "Base64 encoded PNG image of a QR code linking to the collection URL.", "type": "string", "format": "byte" } } }, "idv_document_type": { "title": "idv_document_type", "type": "object", "properties": { "type": { "description": "The type of document identified (e.g., Drivers License, Passport).", "type": "string", "example": "Drivers License" }, "country": { "description": "The country of issuance.", "type": "string", "example": "USA" }, "state": { "description": "The state/province of issuance (if applicable).", "type": "string", "example": "CO" } } }, "idv_document_data": { "title": "idv_document_data", "type": "object", "properties": { "first_name": { "description": "First name extracted from the document.", "type": "string", "example": "Dwayne" }, "sur_name": { "description": "Last name extracted from the document.", "type": "string", "example": "Denver" }, "full_name": { "description": "Full name extracted from the document.", "type": "string", "example": "Dwayne Denver" }, "address": { "description": "Address extracted from the document.", "type": "string", "example": "123 Example Street, New York City, NY 10001" }, "parsed_address": { "description": "Address components parsed from the extracted address.", "type": "object", "properties": { "physical_address": { "description": "The primary address line of the address.", "type": "string" }, "physical_address2": { "description": "The secondary address line of the address.", "type": "string" }, "city": { "description": "The city of the address.", "type": "string" }, "state": { "description": "The state of the address.", "type": "string" }, "country": { "description": "The country of the address.", "type": "string" }, "zip": { "description": "The ZIP code of the address.", "type": "string" } } }, "document_number": { "description": "Document identification number.", "type": "string", "example": "000000000" }, "dob": { "description": "Date of birth extracted from the document.", "type": "string", "format": "date", "example": "1990-01-01" }, "issue_date": { "description": "Date the document was issued.", "type": "string", "format": "date", "example": "2020-01-01" }, "expiration_date": { "description": "Date the document expires.", "type": "string", "format": "date", "example": "2027-01-01" } } }, "idv_result_document_verification": { "title": "idv_result_document_verification", "type": "object", "properties": { "status": { "description": "The current status of the document verification process.", "type": "string", "enum": [ "started", "documents_collected", "complete" ] }, "result": { "description": "The final result of the verification, or null if not complete.", "type": "string", "enum": [ "accept", "reject", "resubmit", "failed" ] }, "errors": { "description": "List of error codes if the process failed or encountered issues (e.g., consent_declined, session_expired).", "$ref": "#/components/schemas/errors" }, "collection_link": { "description": "Link details for the document collection step.", "$ref": "#/components/schemas/idv_collection_link" }, "result_context": { "description": "Array of objects describing reasons or context associated with the result.", "type": "array", "items": { "$ref": "#/components/schemas/idv_result_context_item" }, "example": [ { "code": "CT-0167", "title": "First name extracted from document correlates with input name", "category": "informational" }, { "code": "CT-0171", "title": "Document number extracted from document correlates with input number", "category": "informational" } ] }, "document_type": { "description": "Details about the type of document submitted.", "$ref": "#/components/schemas/idv_document_type" }, "document_data": { "description": "Data extracted from the submitted document.", "$ref": "#/components/schemas/idv_document_data" } }, "example": { "status": "complete", "result": "accept", "errors": [], "collection_link": { "url": "https://example.com", "qr_code": "" }, "result_context": [ { "code": "CT-0167", "title": "First name extracted from document correlates with input name", "category": "informational" }, { "code": "CT-0171", "title": "Document number extracted from document correlates with input number", "category": "informational" } ], "document_type": { "type": "Drivers License", "country": "USA", "state": "CO" }, "document_data": { "first_name": "Dwayne", "sur_name": "Denver", "full_name": "Dwayne Denver", "address": "123 Example Street, New York City, NY 10001", "parsed_address": { "physical_address": "123 Example Street", "physical_address2": "Suite 200", "city": "New York City", "state": "NY", "zip": "10001", "country": "USA" }, "document_number": "000000000", "dob": "2000-01-01", "issue_date": "2020-01-01", "expiration_date": "2027-01-01" } } }, "idv_result_personal_identity_records": { "title": "idv_result_personal_identity_records", "description": "Results for a `personal_identity_records` identity verification. SSN values in\n`people[].ssn` are masked as `XXX-XX-{last4}` by default; use the `unmask_ssn`\nquery parameter or product configuration to return full values. SSN may be null\nwhen the provider has no SSN on file for a record.\n", "type": "object", "properties": { "request": { "description": "The request parameters used for the search", "type": "object", "properties": { "first_name": { "description": "The first name of the person", "type": "string" }, "middle_name": { "description": "The middle name of the person", "type": "string" }, "last_name": { "description": "The last name of the person", "type": "string" }, "dob": { "$ref": "#/components/schemas/date_string_complete" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "email": { "$ref": "#/components/schemas/email_string" }, "ssn": { "$ref": "#/components/schemas/ssn_string" }, "address": { "$ref": "#/components/schemas/address" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } } }, "people": { "description": "Array of identity records found matching the search criteria", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The person's name components", "type": "object", "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" } } }, "dobs": { "description": "Array of dates of birth associated with this identity (format YYYYMMDD, with 00 for unknown components)", "type": "array", "items": { "type": "string", "pattern": "^[0-9]{8}$", "example": "19900115" } }, "phones": { "description": "Array of phone numbers associated with this identity", "type": "array", "items": { "type": "string" } }, "ssn": { "description": "Social Security Number for this identity record. Not enabled by default;\ncontact your Checkr Account Executive or Customer Success\nrepresentative if you need SSN in results.\n\nWhen SSN unmasking is disabled, values are returned masked as\n`XXX-XX-{last4}` (see the `unmask_ssn` query parameter). May be null\nwhen the provider has no SSN on file for this record.\n", "oneOf": [ { "$ref": "#/components/schemas/ssn_string" }, { "$ref": "#/components/schemas/masked_ssn_string" }, { "type": "null" } ], "example": "XXX-XX-1234" }, "addresses": { "description": "Array of addresses associated with this identity", "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "county": { "type": "string", "description": "County name" }, "country": { "type": "string" }, "from_date": { "type": "string", "format": "date", "description": "First date the person was associated with this address" }, "to_date": { "type": "string", "format": "date", "description": "Last date the person was associated with this address" } } } }, "aliases": { "description": "Array of name aliases associated with this identity", "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" } } } } } } } }, "example": { "request": { "first_name": "JOHN", "last_name": "SMITH", "dob": "19900115" }, "people": [ { "name": { "first_name": "JOHN", "middle_name": "ALLEN", "last_name": "SMITH", "full_name": "JOHN ALLEN SMITH" }, "dobs": [ "19900115" ], "phones": [ "+15551234567" ], "ssn": "XXX-XX-1234", "addresses": [ { "street": "123 MAIN ST", "city": "ANYTOWN", "state": "CA", "zip_code": "12345", "county": "LINCOLN", "country": "US", "from_date": "2018-03-15", "to_date": "2024-01-20" } ], "aliases": [ { "first_name": "JOHNNY", "last_name": "SMITH" } ] } ] } }, "idv_result_reverse_phone": { "title": "idv_result_reverse_phone", "type": "object", "properties": { "phone_info": { "description": "Technical and geographic information about the phone number.", "type": "object", "properties": { "operating_company": { "description": "The operating carrier associated with the phone number.", "type": "object", "properties": { "category_description": { "type": "string", "description": "Description of the carrier category." }, "name": { "type": "string", "description": "Legal name of the operating company." }, "dba": { "type": "string", "description": "Doing-business-as name of the operating company." }, "common_name": { "type": "string", "description": "Common name of the operating company." }, "type": { "type": "string", "description": "Type of operating company." } } }, "rate_center": { "description": "Geographic rate center information for the phone number.", "type": "object", "properties": { "lata": { "description": "Local Access and Transport Area information.", "type": "object", "properties": { "code": { "type": "string" }, "state": { "type": "string" }, "state_name": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "location": { "type": "string" } } }, "bta": { "description": "Basic Trading Area information.", "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "mtas": { "description": "Major Trading Areas associated with the rate center.", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "country": { "type": "string" }, "market_name": { "type": "string" } } } }, "cbsas": { "description": "Core Based Statistical Areas associated with the rate center.", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "csa": { "type": "integer" }, "area_name": { "type": "string" }, "area_type": { "type": "string" }, "state": { "type": "string" } } } }, "counties": { "description": "Counties associated with the rate center.", "type": "array", "items": { "type": "object", "properties": { "fips_code": { "type": "string", "description": "US county FIPS code" }, "name": { "type": "string" }, "type": { "type": "string" }, "state": { "type": "string" }, "state_name": { "type": "string" }, "county": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "land_area_square_miles": { "type": "number" }, "population_in_2006": { "type": "integer" } } } }, "zip_codes": { "description": "ZIP codes associated with the rate center.", "type": "array", "items": { "type": "string" } }, "city": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "state": { "type": "string" }, "state_name": { "type": "string" }, "time_zone": { "type": "string" }, "time_zone_name": { "type": "string" }, "dst_recognized": { "type": "string", "description": "Whether daylight saving time is recognized in this area." } } }, "npa": { "type": "integer", "description": "Numbering Plan Area (area code)." }, "nxx": { "type": "integer", "description": "Central office code (exchange)." }, "block_id": { "type": "string", "description": "Block identifier for the phone number." }, "line_type": { "type": "string", "description": "Type of phone line (e.g. Mobile, Landline, VOIP)." }, "central_office_name": { "type": "string", "description": "Name of the central office serving this number." }, "switch": { "type": "string", "description": "Switch identifier for the central office." }, "derived_from_npa": { "type": "integer", "description": "Original NPA if the number was derived from a different area code." }, "new_npa": { "type": "string", "description": "New NPA if the number has been reassigned." }, "overlay": { "type": "string", "description": "Overlay area code, if applicable." }, "nxx_type": { "type": "string", "description": "Type classification of the NXX code." }, "nxx_description": { "type": "string", "description": "Description of the NXX type." } } }, "persons": { "description": "Array of identity records associated with the phone number.", "type": "array", "items": { "type": "object", "properties": { "names": { "description": "Names associated with this identity.", "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "prefixes": { "type": "string" }, "maiden_name": { "type": "string" }, "suffixes": { "type": "string" } } } }, "addresses": { "description": "Addresses associated with this identity.", "type": "array", "items": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "address3": { "type": "string" }, "house_num": { "type": "string" }, "unit_num": { "type": "string" }, "unit_type": { "type": "string" }, "county": { "type": "string" }, "county_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "state_code": { "type": "string" }, "city_state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" }, "zip_code": { "type": "string" }, "zip_code4": { "type": "string" }, "date_from": { "type": "string" }, "date_from_year": { "type": "integer" }, "date_from_month": { "type": "integer" }, "date_from_day": { "type": "integer" }, "date_to": { "type": "string" }, "date_to_year": { "type": "integer" }, "date_to_month": { "type": "integer" }, "date_to_day": { "type": "integer" } } } }, "phones": { "description": "Phone numbers associated with this identity.", "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "country_code": { "type": "string" }, "formatted": { "type": "string" }, "valid_since": { "type": "string", "format": "date-time" }, "type": { "type": "string" } } } }, "email": { "type": "string", "description": "Email address associated with this identity." }, "days_email_has_been_active": { "type": "string", "description": "Number of days the email address has been active." }, "gender": { "type": "string", "enum": [ "unknown", "male", "female" ], "description": "Gender associated with this identity." }, "dob": { "type": "string", "description": "Date of birth associated with this identity." }, "social_profiles": { "description": "Social media profiles associated with this identity.", "type": "array", "items": { "type": "object", "properties": { "exists": { "type": "boolean" }, "user_name": { "type": "string" }, "num_friends": { "type": "string" }, "profile_url": { "type": "string" }, "image_url": { "type": "string" }, "site": { "type": "string" }, "site_url": { "type": "string" } } } }, "user_ids": { "description": "User identifiers associated with this identity.", "type": "array", "items": { "type": "string" } }, "user_names": { "description": "Usernames associated with this identity.", "type": "array", "items": { "type": "string" } }, "relationships": { "description": "Relationships associated with this identity.", "type": "array", "items": { "type": "object" } } } } }, "date_executed": { "type": "string", "description": "The date and time the phone search was executed." }, "total_time_in_seconds": { "type": "number", "description": "Total time taken to execute the phone search, in seconds." } } }, "idv_type": { "description": "The type of identity verification to be done.", "type": "string", "title": "idv_type", "enum": [ "pii_validation", "document_verification", "personal_identity_records", "reverse_phone" ], "x-enumDescriptions": { "pii_validation": "When requesting pii_validation, the result will be returned immediately.", "document_verification": "When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook.", "personal_identity_records": "When requesting personal_identity_records, enriched identity information will be returned immediately.", "reverse_phone": "When requesting reverse_phone, identity information associated with the provided phone number will be returned immediately." }, "default": "pii_validation" }, "identity_verification": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "description": "The structure of results depends on the value of idv_type.", "oneOf": [ { "$ref": "#/components/schemas/idv_result_pii_validation" }, { "$ref": "#/components/schemas/idv_result_document_verification" }, { "$ref": "#/components/schemas/idv_result_personal_identity_records" }, { "$ref": "#/components/schemas/idv_result_reverse_phone" } ] }, "idv_type": { "$ref": "#/components/schemas/idv_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "identity verification with profile id", "required": [ "profile_id" ] }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "identity verification with profile object", "required": [ "profile" ] } ] }, "identifying_attribute_required": { "type": "object", "description": "At least one identifying attribute must be provided alongside the name: `dob`, `phone`,\n`email`, `ssn`, `address`, or `addresses`.\n", "not": { "allOf": [ { "not": { "required": [ "dob" ] } }, { "not": { "required": [ "phone" ] } }, { "not": { "required": [ "email" ] } }, { "not": { "required": [ "ssn" ] } }, { "not": { "required": [ "address" ] } }, { "not": { "required": [ "addresses" ] } } ] } }, "identity-verification-request-from-pii": { "description": "the request to create a new identity verification from set of PII", "type": "object", "properties": { "idv_type": { "$ref": "#/components/schemas/idv_type" }, "first_name": { "description": "The first name of the person. Required (with last_name) when not sending full_name.", "type": "string" }, "middle_name": { "description": "For document verification, the middle name of the person.", "type": "string" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "The last name of the person. Required (with first_name) when not sending full_name.", "type": "string" }, "full_name": { "description": "Either send the full name, or first and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\nIf you already know the first and last names, we suggest sending them.\n", "type": "string", "example": "Jane Doe" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "phone": { "$ref": "#/components/schemas/phone_string" }, "email": { "$ref": "#/components/schemas/email_string" }, "ssn": { "$ref": "#/components/schemas/ssn_string" }, "address": { "$ref": "#/components/schemas/address", "description": "{% partial file=\"/_partials/schema-address-field-prefer-addresses-array.md\" /%}\n" }, "addresses": { "description": "{% partial file=\"/_partials/schema-idv-addresses-field.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "send_message": { "description": "For document verification, whether the end user should receive an SMS with the collection link to the provided phone number.\nDefaults to false if not provided.\n", "type": "boolean", "default": false }, "skip_selfie": { "description": "For document verification, whether we should skip collecting and verifying a selfie. Defaults to false.", "type": "boolean", "default": false } }, "required": [ "idv_type" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" }, { "$ref": "#/components/schemas/identifying_attribute_required" } ], "example": { "first_name": "JOHN", "last_name": "SMITH", "idv_type": "pii_validation", "email": "j.doe@example.com" } }, "identity-verification-request-from-profile": { "description": "Create an identity verification from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request` (`reference_id` and `no_middle_name` may accompany `profile_id`).\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "properties": { "idv_type": { "$ref": "#/components/schemas/idv_type" }, "profile_id": { "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "send_message": { "description": "For document verification, whether the end user should receive an SMS with the collection link to the provided phone number. Defaults to false if not provided.", "type": "boolean" }, "skip_selfie": { "description": "For document verification, whether we should skip collecting and verifying a selfie. Defaults to false.", "type": "boolean", "default": false } }, "required": [ "profile_id", "idv_type" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080", "idv_type": "pii_validation" } }, "identity-verification-request-from-phone": { "description": "the request to create a new reverse phone identity verification", "type": "object", "properties": { "idv_type": { "$ref": "#/components/schemas/idv_type" }, "country_code": { "description": "The country code of the phone number (e.g. \"1\" for US).", "type": "string" }, "phone": { "description": "The phone number to look up (e.g. \"310-555-5555\").", "type": "string" } }, "required": [ "idv_type", "country_code", "phone" ], "example": { "idv_type": "reverse_phone", "country_code": "1", "phone": "310-555-5555" } }, "idv_result_document_verification_initial": { "title": "idv_result_document_verification_initial", "type": "object", "properties": { "status": { "type": "string", "enum": [ "started" ], "description": "The initial status of the document verification process." }, "collection_link": { "$ref": "#/components/schemas/idv_collection_link", "description": "Link details for the document collection step." } }, "required": [ "status", "collection_link" ] }, "identity_verification_post_response": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "the UUID of the identity verification." }, "created_at": { "$ref": "#/components/schemas/datetime" }, "results": { "description": "The structure of results depends on the value of idv_type.", "oneOf": [ { "$ref": "#/components/schemas/idv_result_pii_validation" }, { "$ref": "#/components/schemas/idv_result_document_verification_initial" }, { "$ref": "#/components/schemas/idv_result_personal_identity_records" }, { "$ref": "#/components/schemas/idv_result_reverse_phone" } ] }, "profile_id": { "$ref": "#/components/schemas/uuid", "description": "the UUID of the profile." }, "profile": { "$ref": "#/components/schemas/profile" }, "idv_type": { "$ref": "#/components/schemas/idv_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "required": [ "id", "created_at", "results", "idv_type" ] }, "document-verification-completed-event-body": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "document_verification.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "oneOf": [ { "$ref": "#/components/schemas/idv_result_document_verification" } ], "description": "The structure of results depends on the value of idv_type." }, "profile_id": { "type": "string", "format": "uuid" }, "idv_type": { "type": "string", "enum": [ "document_verification" ] }, "reference_id": { "$ref": "#/components/schemas/reference_id" } } }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "profile_request_from_pii": { "description": "The request to create a new profile from a set of personally identifiable information (PII).\nExactly one name format must be provided: either full_name (without first_name, middle_name, or\nlast_name) or first_name and last_name (without full_name).\n`no_middle_name` may accompany either format. When supplied with `full_name`, the parsed middle\ntoken is folded into the surname (see the shared `no_middle_name` schema).\nAt least one of the following must also be provided - DOB, phone, email, address, or SSN.\nThe more identity fields provided (SSN, email, phone), the better the matching and verification capabilities will be.\nThese fields are used for additional identity verification and record matching in various check products.\n", "type": "object", "properties": { "full_name": { "description": "The full name of the person. Must not be combined with first_name, middle_name, or last_name.\nMay be combined with `no_middle_name`; when that flag is `true`, parsing stores only a first\nname and surname (any middle token is folded into the last name).\n", "type": "string" }, "first_name": { "description": "The first name of the person.", "type": "string" }, "middle_name": { "description": "The middle name of the person. Can be null if not provided.", "type": "string" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "The last name of the person.", "type": "string" }, "dob": { "$ref": "#/components/schemas/date_string_complete" }, "phone": { "description": "A phone number in the form +[country code][number including area code]. (E.164 format)\nA U.S. number supplied in national format (for example \"(415) 555-0123\") is normalized to\nE.164 on write. If invalid, the API returns a 400 with a `validation_error`.\n", "$ref": "#/components/schemas/phone_string" }, "email": { "$ref": "#/components/schemas/email_string" }, "ssn": { "$ref": "#/components/schemas/ssn_string" }, "address": { "$ref": "#/components/schemas/address" }, "addresses": { "$ref": "#/components/schemas/addresses" }, "custom_id": { "$ref": "#/components/schemas/custom_id_string" } }, "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" }, { "$ref": "#/components/schemas/identifying_attribute_required" } ], "example": { "first_name": "JOHN", "middle_name": "ROBERT", "last_name": "SMITH", "dob": "19900101", "ssn": "123-45-6789", "email": "john.smith@example.com", "phone": "+14155552671", "address": { "street": "123 Main St", "city": "San Francisco", "state": "CA", "zip_code": "94105" }, "custom_id": "employee-123" } }, "profile_request_from_address": { "description": "The request to create a new profile from an address only. This is used when you only have address information and no personal identifiers.", "type": "object", "properties": { "address": { "$ref": "#/components/schemas/address" }, "addresses": { "$ref": "#/components/schemas/addresses" }, "custom_id": { "$ref": "#/components/schemas/custom_id_string" } }, "required": [ "address" ], "example": { "address": { "street": "123 Example Street", "city": "New York City", "state": "NY", "zip_code": "10001", "country": "US" } } }, "profile_request_from_profile": { "description": "The request to create a new profile by copying an existing profile's information. This allows reusing previously validated profile data.", "type": "object", "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "custom_id": { "$ref": "#/components/schemas/custom_id_string" } }, "required": [ "profile_id" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080" } }, "legal_check": { "type": "object", "description": "A legal annotation check result indicating how a record, case, or charge\nwas evaluated against applicable legal rules.\n", "properties": { "action_type": { "type": "string", "description": "The action type determined by the legal rule evaluation:\n- note: Informational annotation added to the item\n- investigate: The item may require further review before inclusion\n- remove: The item should not be reported based on legal restrictions\n- modified: The item was modified (e.g., certain attributes were removed)\n", "enum": [ "note", "investigate", "remove", "modified" ], "example": "note" }, "rule_id": { "type": "string", "description": "Identifier of the legal rule that triggered this check result.", "example": "CA-7yr-felony" }, "rule_type": { "type": "string", "description": "The type of rule that was applied:\n- legal: A rule based on statutory or regulatory requirements\n- policy: A rule based on company policy\n", "enum": [ "legal", "policy" ], "example": "legal" }, "domain": { "type": "string", "description": "The filter domain in which this rule was applied.", "example": "employment" }, "description": { "type": "string", "description": "Human-readable description of what the legal rule evaluated.", "example": "Felony convictions older than 7 years cannot be reported in California" }, "run_at": { "type": "string", "format": "date-time", "description": "The timestamp when this check was evaluated.", "example": "2024-01-15T10:30:00.000Z" } } }, "regulated_charge": { "description": "A charge with legal annotation checks.", "allOf": [ { "$ref": "#/components/schemas/charge" }, { "type": "object", "properties": { "checks": { "type": "array", "description": "Legal annotation check results for this charge.", "items": { "$ref": "#/components/schemas/legal_check" } } } } ] }, "regulated_case": { "description": "A case with legal annotation checks.", "allOf": [ { "$ref": "#/components/schemas/case_core" }, { "type": "object", "properties": { "charges": { "description": "Charges in this case, with legal annotation checks.", "type": "array", "items": { "$ref": "#/components/schemas/regulated_charge" } }, "checks": { "type": "array", "description": "Legal annotation check results for this case.", "items": { "$ref": "#/components/schemas/legal_check" } } } } ] }, "regulated_record": { "title": "regulated_record", "description": "A criminal record with legal annotation checks at record, case, and charge levels.", "allOf": [ { "$ref": "#/components/schemas/record_core" }, { "type": "object", "properties": { "cases": { "description": "Cases in this record, with legal annotation checks.", "type": "array", "items": { "$ref": "#/components/schemas/regulated_case" } }, "checks": { "type": "array", "description": "Legal annotation check results for this record.", "items": { "$ref": "#/components/schemas/legal_check" } } } } ] }, "regulated_record_stripped": { "title": "regulated_record_stripped", "description": "A reduced view of a record excluded by legal rules, returned in `excluded_records` instead of\n`results` when the account's `excluded_record_disclosure` setting is `stripped` (rather than\nomitting the record entirely). Limited to an identifier, classification, jurisdiction, and\nper-charge offense classification -- no cases, charges, legal annotation checks, or\nperson/identity information.\n", "type": "object", "properties": { "record_id": { "type": "string", "description": "A stable identifier for this record, derived from the record content.\nFormat: `record-{sha256_hash}`.\n", "example": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "category": { "$ref": "#/components/schemas/record_category" }, "source": { "description": "Reduced to jurisdiction fields only (category, state, county).", "type": "object", "properties": { "category": { "$ref": "#/components/schemas/source_category" }, "state": { "$ref": "#/components/schemas/state_code" }, "county": { "type": "string", "description": "The name of the county (if any) where the record came from.", "example": "Franklin" } } }, "offense_classifications": { "description": "Classification of each charge on the excluded record, at the same category/subcategory/\nsubsubcategory granularity as a full record's charges. One entry per charge across all of\nthe record's cases.\n", "type": "array", "items": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/charge_category" }, "subcategory": { "$ref": "#/components/schemas/charge_subcategory" }, "subsubcategory": { "$ref": "#/components/schemas/charge_subsubcategory" } } } } } }, "regulated_check_type": { "type": "string", "description": "The type of regulated check. Currently only instant_criminal_regulated is supported.", "enum": [ "instant_criminal_regulated" ], "default": "instant_criminal_regulated" }, "regulated_check": { "type": "object", "description": "A regulated check response with legal annotation checks included in results.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "description": "The fully-disclosed records found for this check. When there are no results found, this\nwill be an empty array. A record excluded by legal rules never appears here -- see\n`excluded_records`.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record" } }, "excluded_records": { "description": "Records excluded by legal rules, reduced to an identifier, classification, jurisdiction,\nand per-charge offense classification. Present only when the account's\n`excluded_record_disclosure` setting is `stripped`; omitted (or empty) otherwise, and\nalways separate from `results`. Also omitted when `include[]=results_found` is requested,\nsame as `results` itself.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record_stripped" } }, "check_type": { "$ref": "#/components/schemas/regulated_check_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "run_notes": { "description": "An unstructured array of human-readable notes about this particular check.\nMay contain notes about how input was parsed or other information about results.\n", "type": "array", "items": { "type": "string" } }, "results_found": { "description": "Present only when `include[]=results_found` is requested; omitted otherwise.\nWhen present, the `results` array is omitted.\n", "type": "boolean" }, "rulesets_applied": { "description": "Present only when `include[]=rulesets_applied` is requested; omitted otherwise.", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_applied" } }, "review": { "description": "Present only when `include[]=review` is requested; omitted otherwise.\nNull when no accept/decline/dispute decision exists for this check.\n", "oneOf": [ { "$ref": "#/components/schemas/check_review" }, { "type": "null" } ] }, "adverse_action_enabled": { "description": "Present only when `include[]=review` is requested; omitted otherwise.\nIndicates whether adverse-action workflow is enabled for this product.\n", "type": "boolean" } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "regulated check with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "regulated check with profile object" } ] }, "regulated_check_request_from_pii": { "type": "object", "description": "Request to create a regulated check using personally identifiable information (PII).", "properties": { "check_type": { "$ref": "#/components/schemas/regulated_check_type" }, "first_name": { "description": "First name (given name). Do not include prefixes like \"Ms.\" or \"Dr.\"", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name(s)", "type": "string", "example": "Mary Louise" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "Last name (surname). Do not include suffixes like \"Jr.\" or \"2nd\".", "type": "string", "example": "Smith" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\n", "type": "string", "example": "Smith, Jane Mary Louise" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "description": "Social Security Number used for additional identity verification and record matching", "$ref": "#/components/schemas/ssn_string" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "addresses": { "description": "{% partial file=\"/_partials/schema-check-addresses-field-regulated.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "filter_context": { "$ref": "#/components/schemas/filter_context" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" } }, "required": [ "dob", "filter_context", "permissible_purpose" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "JOHN", "last_name": "SMITH", "dob": "19900101", "ssn": "123-45-6789", "phone": "+14155552671", "addresses": [ { "street": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip_code": "90001" } ], "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "regulated_check_request_from_profile": { "description": "Create a regulated check from an existing profile. Do not include inline PII or `addresses` alongside `profile_id`—the API rejects combined requests with `400 Bad Request`.\nIf `no_middle_name` is provided, it is persisted to the referenced profile.\n", "type": "object", "properties": { "check_type": { "$ref": "#/components/schemas/regulated_check_type" }, "profile_id": { "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "filter_context": { "$ref": "#/components/schemas/filter_context" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" } }, "required": [ "profile_id", "filter_context", "permissible_purpose" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080", "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "regulated_case-2": { "description": "A case with legal annotation checks.", "allOf": [ { "$ref": "#/components/schemas/case" }, { "type": "object", "properties": { "charges": { "description": "Charges in this case, with legal annotation checks.", "type": "array", "items": { "$ref": "#/components/schemas/regulated_charge" } }, "checks": { "type": "array", "description": "Legal annotation check results for this case.", "items": { "$ref": "#/components/schemas/legal_check" } } } } ] }, "regulated_record-2": { "title": "regulated_record", "description": "A criminal record with legal annotation checks at record, case, and charge levels.", "allOf": [ { "$ref": "#/components/schemas/record" }, { "type": "object", "properties": { "cases": { "description": "Cases in this record, with legal annotation checks.", "type": "array", "items": { "$ref": "#/components/schemas/regulated_case-2" } }, "checks": { "type": "array", "description": "Legal annotation check results for this record.", "items": { "$ref": "#/components/schemas/legal_check" } } } } ] }, "criminal_report_check_type": { "type": "string", "description": "The type of check performed for this report.", "enum": [ "regulated_criminal_report" ], "default": "regulated_criminal_report" }, "regulated_criminal_report": { "type": "object", "description": "A regulated criminal report with legal annotation checks included in results.\nResults are delivered asynchronously via webhook once processing is complete.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "status": { "type": "string", "description": "The current status of the report.", "enum": [ "pending", "complete", "failed" ], "example": "complete" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "description": "The fully-disclosed records found for this report. When there are no results found, this\nwill be an empty array. A record excluded by legal rules never appears here -- see\n`excluded_records`.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record-2" } }, "excluded_records": { "description": "Records excluded by legal rules, reduced to an identifier, classification, jurisdiction,\nand per-charge offense classification. Present only when the account's\n`excluded_record_disclosure` setting is `stripped`; omitted (or empty) otherwise, and\nalways separate from `results`.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record_stripped" } }, "check_type": { "$ref": "#/components/schemas/criminal_report_check_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "run_notes": { "description": "An unstructured array of human-readable notes about this particular report.\nMay contain notes about how input was parsed or other information about results.\n", "type": "array", "items": { "type": "string" } } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "regulated criminal report with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "regulated criminal report with profile object" } ] }, "filter_domain-2": { "type": "string", "description": "The legal-filtering domain to apply to this report (for example, employment vs. tenancy rules).\n\nThis is only needed when your account is configured to allow multiple filter domains.\nMost callers do not need to set this — a default domain is applied automatically based on\nyour account's configuration. When your account does allow choosing a domain per call, only\na limited, pre-approved set of values is accepted; contact Checkr to configure which domains\nyour account can use.\n", "enum": [ "employment", "long term tenancy", "short term tenancy", "eviction", "other" ], "example": "employment" }, "filter_context-2": { "type": "object", "description": "Context information used to determine which legal rules apply when filtering report results.\nJurisdictions help identify applicable state and local regulations that may affect\nwhich records can be reported.\n", "properties": { "candidate_jurisdiction": { "description": "The jurisdiction where the candidate (subject of the report) is located.", "$ref": "#/components/schemas/jurisdiction" }, "decider_jurisdiction": { "description": "The jurisdiction where the decision-maker (employer/requester) is located.", "$ref": "#/components/schemas/jurisdiction" }, "property_jurisdiction": { "description": "The jurisdiction of the property involved (for tenancy-related reports).", "$ref": "#/components/schemas/jurisdiction" }, "filter_domain": { "$ref": "#/components/schemas/filter_domain-2" } }, "required": [ "candidate_jurisdiction" ] }, "permissible_purpose-2": { "type": "string", "description": "The permissible purpose for requesting this criminal record report, as required by the Fair Credit Reporting Act (FCRA).\nThis must be provided for all regulated criminal reports to ensure compliance with federal regulations.\n", "enum": [ "Court Order", "Consumer Instruction", "Credit Transaction", "Employment", "Insurance Underwriting", "Benefit Eligibility", "Credit Risk", "Consumer Initiated", "Account Review", "Govt Chargecard", "Child Support", "Agency Liquidation" ], "example": "Employment" }, "criminal_report_request_from_pii": { "type": "object", "description": "Request to create a regulated criminal report using personally identifiable information (PII).", "properties": { "check_type": { "$ref": "#/components/schemas/criminal_report_check_type" }, "first_name": { "description": "First name (given name). Do not include prefixes like \"Ms.\" or \"Dr.\"", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name(s)", "type": "string", "example": "Mary Louise" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "Last name (surname). Do not include suffixes like \"Jr.\" or \"2nd\".", "type": "string", "example": "Smith" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\n", "type": "string", "example": "Smith, Jane Mary Louise" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "description": "Social Security Number used for additional identity verification and record matching", "$ref": "#/components/schemas/ssn_string" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "addresses": { "description": "{% partial file=\"/_partials/schema-check-addresses-field-regulated.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "filter_context": { "$ref": "#/components/schemas/filter_context-2" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose-2" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" } }, "required": [ "dob", "filter_context", "permissible_purpose" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "JOHN", "last_name": "SMITH", "dob": "19900101", "ssn": "123-45-6789", "phone": "+14155552671", "addresses": [ { "street": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip_code": "90001" } ], "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "criminal_report_request_from_profile": { "description": "Create a regulated criminal report from an existing profile. Do not include inline PII or `addresses` alongside `profile_id`—the API rejects combined requests with `400 Bad Request` (`reference_id` may accompany `profile_id`).\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "type": "object", "properties": { "check_type": { "$ref": "#/components/schemas/criminal_report_check_type" }, "profile_id": { "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "filter_context": { "$ref": "#/components/schemas/filter_context-2" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose-2" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" } }, "required": [ "profile_id", "filter_context", "permissible_purpose" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080", "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "regulated_criminal_report_created": { "type": "object", "description": "Response returned when a regulated criminal report is created. Full results are delivered asynchronously via webhook.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "status": { "type": "string", "description": "The current status of the report.", "enum": [ "pending", "complete", "failed" ], "example": "pending" } } }, "disqualifying_record": { "type": "object", "description": "A reference to a specific criminal record that contributed to the adverse decision.\nIncluding disqualifying records is optional but strongly recommended for FCRA compliance -\nthe subject must be informed of which records triggered the decision.\nrecord_id is globally unique across all checks.\n", "properties": { "record_id": { "type": "string", "description": "The ID of the criminal record within a check result.", "example": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" } }, "required": [ "record_id" ] }, "pre_adverse_action_request": { "type": "object", "description": "Request to send a pre-adverse action notification to the subject identified by `check_id`.\nThis ensures compliance and fairness in the decision-making process.\n\nCannot be submitted after an `adverse_action` has already been taken for this check.\n", "properties": { "check_id": { "$ref": "#/components/schemas/uuid", "description": "The ID of the regulated check that produced the records for this pre-adverse action." }, "email": { "$ref": "#/components/schemas/email_string", "description": "Email address of the subject to deliver the notice to." }, "suppress_notice": { "type": "boolean", "default": false, "description": "When `true`, the notice email is not sent to the subject. The `candidate_report_url`\nis still populated in the response. Defaults to `false`.\n" }, "disqualifying_records": { "type": "array", "description": "The criminal records that triggered the adverse decision. Optional but recommended.", "items": { "$ref": "#/components/schemas/disqualifying_record" } } }, "required": [ "check_id", "email" ], "example": { "check_id": "a3f1e290-bc44-4d2a-9c18-d3e5f2a71b00", "email": "john.smith@example.com", "disqualifying_records": [ { "record_id": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" } ] } }, "pre_adverse_action_response": { "type": "object", "description": "A pre-adverse action record.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "check_id": { "$ref": "#/components/schemas/uuid", "description": "The ID of the regulated check that produced the records for this pre-adverse action." }, "status": { "type": "string", "description": "The status associated with the pre-adverse action.", "example": "AdverseActionInitiated" }, "candidate_report_url": { "type": [ "string", "null" ], "format": "uri", "description": "Subject-facing URL for viewing the background check report and responding to the notice.\nWhen a subject UI is configured this is a deep link keyed by the pre-adverse action id,\ngated by a one-time code sent to the subject's email so the customer cannot open it\ndirectly; you may still share it with the subject, and Checkr emails it to them unless\n`suppress_notice` is set. Where no subject UI is configured, this is a support `mailto:`\nlink instead (no OTP gating).\n", "example": "https://subjects.checkrtrust.com/2b8313e8-4efd-45a1-b578-952b8313e890/review" }, "disqualifying_records": { "type": "array", "items": { "$ref": "#/components/schemas/disqualifying_record" } }, "created_at": { "$ref": "#/components/schemas/datetime" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the notice was delivered. Null until status is `sent`.", "example": "2024-06-01T14:00:00Z" } } }, "pre-adverse-action-completed-event-body": { "type": "object", "description": "Emitted when the subject accepts a pre-adverse action decision (`Closed`). The payload is\nintentionally minimal: retrieve full details via `GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "pre_adverse_action.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "pre_adverse_action_id": { "$ref": "#/components/schemas/uuid", "description": "ID of the pre-adverse action that reached a terminal state." }, "status": { "type": "string", "enum": [ "Closed" ], "description": "Terminal status the pre-adverse action transitioned to.\n`Closed` — subject accepted the decision.\n" } }, "required": [ "pre_adverse_action_id", "status" ] }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "adverse-action-dispute-filed-event-body": { "type": "object", "description": "Emitted when a subject files a dispute against a (pre-)adverse action. Fires for both\npre-adverse and final-adverse disputes; use `data.adverse_action_type` to distinguish them.\n\nThe payload is intentionally minimal. To retrieve full details — including\n`dispute_filed_at` / `dispute_resolved_at` — fetch the parent (pre-)adverse action:\n- `adverse_action_type: pre_adverse_action` → `GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`\n- `adverse_action_type: adverse_action` → `GET /v1/regulated/adverse_actions/{adverse_action_id}`\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "adverse_action.dispute_filed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "adverse_action_id": { "$ref": "#/components/schemas/uuid", "description": "ID of the (pre-)adverse action the dispute was filed against. Use with\n`adverse_action_type` to call the matching GET endpoint for full details.\n" }, "adverse_action_dispute_id": { "$ref": "#/components/schemas/uuid", "description": "ID of the dispute record." }, "adverse_action_type": { "type": "string", "enum": [ "pre_adverse_action", "adverse_action" ], "description": "Which lifecycle stage the dispute belongs to, and which GET endpoint to call.\n`pre_adverse_action` — dispute against a pre-adverse action notice\n(`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`).\n`adverse_action` — dispute against a final adverse action\n(`GET /v1/regulated/adverse_actions/{adverse_action_id}`).\n" }, "status": { "type": "string", "enum": [ "DisputeFiled" ], "description": "Status of the adverse action after the dispute was filed." } }, "required": [ "adverse_action_id", "adverse_action_dispute_id", "adverse_action_type", "status" ] }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "adverse-action-dispute-resolved-event-body": { "type": "object", "description": "Emitted when an admin resolves a filed dispute, either with changes to the report\n(`DisputeResolvedWithChanges`) or without (`DisputeResolvedWithoutChanges`). Fires for both\npre-adverse and final-adverse disputes; use `data.adverse_action_type` to distinguish them.\n\nThe payload is intentionally minimal. To retrieve full details — including\n`dispute_filed_at` / `dispute_resolved_at` — fetch the parent (pre-)adverse action:\n- `adverse_action_type: pre_adverse_action` → `GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`\n- `adverse_action_type: adverse_action` → `GET /v1/regulated/adverse_actions/{adverse_action_id}`\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "adverse_action.dispute_resolved" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "adverse_action_id": { "$ref": "#/components/schemas/uuid", "description": "ID of the (pre-)adverse action whose dispute was resolved. Use with\n`adverse_action_type` to call the matching GET endpoint for full details.\n" }, "adverse_action_dispute_id": { "$ref": "#/components/schemas/uuid", "description": "ID of the dispute record." }, "adverse_action_type": { "type": "string", "enum": [ "pre_adverse_action", "adverse_action" ], "description": "Which lifecycle stage the dispute belongs to, and which GET endpoint to call.\n`pre_adverse_action` — dispute against a pre-adverse action notice\n(`GET /v1/regulated/pre_adverse_actions/{pre_adverse_action_id}`).\n`adverse_action` — dispute against a final adverse action\n(`GET /v1/regulated/adverse_actions/{adverse_action_id}`).\n" }, "status": { "type": "string", "enum": [ "DisputeResolvedWithChanges", "DisputeResolvedWithoutChanges" ], "description": "Resolution outcome.\n`DisputeResolvedWithChanges` — the report was adjusted; reassess the subject's eligibility.\n`DisputeResolvedWithoutChanges` — the report stands as-is.\n" } }, "required": [ "adverse_action_id", "adverse_action_dispute_id", "adverse_action_type", "status" ] }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "pre_adverse_action_record_context": { "type": "object", "description": "Additional context provided by the subject for a specific record.", "properties": { "record_id": { "type": "string", "description": "The ID of the record the subject is providing context for.", "example": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "context": { "type": "string", "description": "Additional context or explanation from the subject related to the record.", "example": "This charge was expunged in 2019." }, "has_attachments": { "type": "boolean", "description": "Indicates whether the subject uploaded supporting attachments for this record.", "example": false } } }, "pre_adverse_action_dispute": { "type": "object", "description": "A dispute filed by the subject against a specific disqualifying record.", "properties": { "record_id": { "type": "string", "description": "The ID of the record being disputed.", "example": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" }, "issue_type": { "type": "string", "description": "The nature of the dispute.", "enum": [ "charges_not_mine", "charges_incorrect", "charges_should_not_show", "duplicate_record", "other_error" ], "example": "charges_not_mine" }, "explanation": { "type": "string", "description": "The subject's explanation for the dispute.", "example": "I have never lived in that state." } } }, "pre_adverse_action_pii": { "type": [ "object", "null" ], "description": "Updated personal information provided by the subject to support their response or dispute.", "properties": { "first_name": { "type": "string", "example": "John" }, "middle_name": { "type": "string", "example": "D" }, "last_name": { "type": "string", "example": "Smith" }, "birth_month": { "type": "integer", "example": 5 }, "birth_day": { "type": "integer", "example": 25 }, "birth_year": { "type": "integer", "example": 1980 }, "ssn": { "type": "string", "example": "XXX-XX-6789" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main St" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zip_code": { "type": "string", "example": "73301" } } } }, "identification_documents": { "type": "array", "items": { "type": "object", "properties": { "driver_license": { "type": [ "object", "null" ], "properties": { "license_number": { "type": "string" }, "license_state": { "type": "string" } } }, "state_id": { "type": [ "object", "null" ], "properties": { "id_number": { "type": "string" }, "issuing_state": { "type": "string" } } }, "passport": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" } } } } } } } }, "pre_adverse_action_feedback": { "type": [ "object", "null" ], "description": "Information provided by the subject in response to the pre-adverse action notice.\nOnly populated after the subject has reviewed and responded to the notice.\n", "properties": { "user_provided_answer": { "type": "string", "description": "Whether the subject acknowledges the records.", "enum": [ "none", "yes", "no", "do_not_share" ], "example": "no" }, "contexts": { "type": "array", "description": "Context provided by the subject for specific records.", "items": { "$ref": "#/components/schemas/pre_adverse_action_record_context" } }, "disputes": { "type": "array", "description": "Disputes filed by the subject against specific records.", "items": { "$ref": "#/components/schemas/pre_adverse_action_dispute" } }, "pii": { "$ref": "#/components/schemas/pre_adverse_action_pii" } } }, "pre_adverse_action_detail_response": { "allOf": [ { "$ref": "#/components/schemas/pre_adverse_action_response" }, { "type": "object", "properties": { "feedback": { "$ref": "#/components/schemas/pre_adverse_action_feedback" }, "dispute_filed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the subject filed a dispute. Null until a dispute is filed.", "example": "2024-06-05T09:30:00Z" }, "dispute_resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the dispute was resolved. Null until resolved.", "example": "2024-06-15T11:00:00Z" } } } ] }, "adverse_action_request": { "type": "object", "description": "Request to finalize an adverse decision against the subject identified by `check_id`.\nUse this when your organization is declining a subject based in whole or in part on the\nresults of a Checkr background check.\n\nDelivers the required adverse action notice to the subject so they can seek assistance\nor initiate a dispute. In the event a dispute is resolved with changes to the report,\nCheckr will notify your organization so you can reassess the subject's eligibility.\n\nMay be submitted with or without a prior pre-adverse action.\n", "properties": { "check_id": { "$ref": "#/components/schemas/uuid", "description": "The ID of the regulated check that produced the records for this adverse action." }, "email": { "$ref": "#/components/schemas/email_string", "description": "Email address of the subject to deliver the notice to." }, "suppress_notice": { "type": "boolean", "default": false, "description": "When `true`, the notice email is not sent to the subject. The `candidate_report_url`\nis still populated in the response. Defaults to `false`.\n" }, "disqualifying_records": { "type": "array", "description": "The criminal records that triggered the adverse decision. Optional but recommended.", "items": { "$ref": "#/components/schemas/disqualifying_record" } } }, "required": [ "check_id", "email" ], "example": { "check_id": "a3f1e290-bc44-4d2a-9c18-d3e5f2a71b00", "email": "john.smith@example.com", "disqualifying_records": [ { "record_id": "record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e" } ] } }, "adverse_action_response": { "type": "object", "description": "An adverse action record.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "check_id": { "$ref": "#/components/schemas/uuid", "description": "The ID of the regulated check that produced the records for this adverse action." }, "status": { "type": "string", "description": "The status associated with the adverse action.", "example": "AdverseActionInitiated" }, "candidate_report_url": { "type": [ "string", "null" ], "format": "uri", "description": "Subject-facing URL for viewing the background check report and responding to the notice.\nWhen a subject UI is configured this is a deep link keyed by the adverse action id,\ngated by a one-time code sent to the subject's email so the customer cannot open it\ndirectly; you may still share it with the subject, and Checkr emails it to them unless\n`suppress_notice` is set. Where no subject UI is configured, this is a support `mailto:`\nlink instead (no OTP gating).\n", "example": "https://subjects.checkrtrust.com/2b8313e8-4efd-45a1-b578-952b8313e890/review" }, "disqualifying_records": { "type": "array", "items": { "$ref": "#/components/schemas/disqualifying_record" } }, "created_at": { "$ref": "#/components/schemas/datetime" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the notice was delivered. Null until status is `sent`.", "example": "2024-06-01T14:00:00Z" } } }, "adverse_action_detail_response": { "allOf": [ { "$ref": "#/components/schemas/adverse_action_response" }, { "type": "object", "properties": { "dispute_filed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the subject filed a dispute. Null until a dispute is filed.", "example": "2024-06-05T09:30:00Z" }, "dispute_resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the dispute was resolved. Null until resolved.", "example": "2024-06-15T11:00:00Z" } } } ] }, "county_fips_code_or_statewide": { "description": "Use a 5-digit county FIPS code for a county-level criminal search. Use the literal `statewide` for a\nstate-level criminal search covering the jurisdiction identified by `state` (the API accepts `statewide`\ncase-insensitively and normalizes it to lowercase in stored search criteria).\n", "oneOf": [ { "type": "string", "pattern": "^\\d{5}$", "example": "06075" }, { "type": "string", "enum": [ "statewide" ] } ] }, "regulated_county_check_request_from_pii": { "description": "Request to create a regulated county check using personally identifiable information (PII).\nSet county_fips_code to the literal `statewide` to perform a state-level search instead of a county-level search.\nA permissible purpose must be provided to comply with FCRA requirements.\n", "type": "object", "properties": { "first_name": { "description": "First name (given name). Do not include prefixes like \"Ms.\" or \"Dr.\"", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name(s)", "type": "string", "example": "Mary" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "Last name (surname). Do not include suffixes like \"Jr.\" or \"2nd\".", "type": "string", "example": "Smith" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\n", "type": "string", "example": "Jane Mary Smith" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "state": { "description": "The two-letter US state code for the search jurisdiction.", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "filter_context": { "$ref": "#/components/schemas/filter_context" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "address": { "$ref": "#/components/schemas/address", "description": "{% partial file=\"/_partials/schema-county-check-address-field.md\" /%}\n" }, "addresses": { "description": "{% partial file=\"/_partials/schema-county-check-addresses-field.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. Pass a single-element array if you only have one ruleset to apply.\nNote: county check rulesets do not support `dob_matching_level`, `dob_types_requiring_address_match`, or `source_states`.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } } }, "required": [ "dob", "state", "county_fips_code", "filter_context", "permissible_purpose" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "Jane", "middle_name": "Mary", "last_name": "Smith", "dob": "19900115", "state": "CA", "county_fips_code": "06075", "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "regulated_county_check_request_from_profile": { "description": "Create a regulated county check from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request` (`reference_id` may accompany `profile_id`).\nSet county_fips_code to the literal `statewide` to perform a state-level search instead of a county-level search.\nA permissible purpose must be provided to comply with FCRA requirements.\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "type": "object", "properties": { "profile_id": { "description": "The unique identifier of an existing profile containing PII.", "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "state": { "description": "The two-letter US state code for the search jurisdiction.", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "filter_context": { "$ref": "#/components/schemas/filter_context" }, "permissible_purpose": { "$ref": "#/components/schemas/permissible_purpose" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. Pass a single-element array if you only have one ruleset to apply.\nNote: county check rulesets do not support `dob_matching_level`, `dob_types_requiring_address_match`, or `source_states`.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } } }, "required": [ "profile_id", "state", "county_fips_code", "filter_context", "permissible_purpose" ], "example": { "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890", "state": "CA", "county_fips_code": "06075", "filter_context": { "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }, "permissible_purpose": "Employment" } }, "regulated_county_check_request": { "description": "Request to create a regulated county check, either from PII or from an existing profile.\n`county_fips_code` is required: pass a 5-digit FIPS code for a county-level check, or the literal `statewide` for a state-level check.\n", "oneOf": [ { "$ref": "#/components/schemas/regulated_county_check_request_from_pii" }, { "$ref": "#/components/schemas/regulated_county_check_request_from_profile" } ] }, "regulated_county_check_type": { "description": "The type of regulated county check.", "type": "string", "title": "regulated_county_check_type", "enum": [ "county_criminal_regulated" ], "default": "county_criminal_regulated" }, "regulated_county_check_status": { "description": "The current status of the regulated county check.\n- `pending` — the check has been submitted and is awaiting results.\n- `complete` — results are available.\n- `cancelled` — the search was cancelled, either at your request or because it could not\n be completed. When a search cannot be completed, a `county_check.not_available` webhook\n is delivered.\n", "type": "string", "title": "regulated_county_check_status", "enum": [ "pending", "complete", "cancelled" ], "example": "pending" }, "check_error_reason": { "description": "A machine-readable reason for a check's error status. Only present when the check has errored.\n- `provider_error` — the third-party data provider returned an unrecoverable error.\n- `timeout` — the check did not complete within the allowed time window.\n- `cancelled` — the check was cancelled, either at your request or because it could not be completed.\n- `need_more_info` — additional identity information (e.g. email or SSN) is required to view results.\n", "type": "string", "title": "check_error_reason", "enum": [ "provider_error", "timeout", "cancelled", "need_more_info" ], "example": "cancelled" }, "regulated_county_check_search_criteria": { "description": "The search criteria used for the regulated county check.", "type": "object", "properties": { "first_name": { "description": "First name of the person.", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name of the person.", "type": "string", "example": "Mary" }, "last_name": { "description": "Last name of the person.", "type": "string", "example": "Smith" }, "date_of_birth": { "description": "Date of birth in the form YYYY-MM-DD.", "allOf": [ { "$ref": "#/components/schemas/date" } ] }, "state": { "description": "The two-letter US state code.", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "description": "The FIPS code for the county, or the literal `statewide` for a state-level check.\n", "$ref": "#/components/schemas/county_fips_code_or_statewide" } } }, "run_notes": { "description": "An unstructured array of human-readable notes about this particular check.\nMay contain notes about how input was parsed or other information about results.\nNot intended to be parsed by computer, as these notes are not guaranteed to be in any given format.\n", "type": "array", "items": { "type": "string", "example": "used no ruleset" } }, "regulated_county_check": { "type": "object", "description": "A regulated county criminal check response.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "description": "The timestamp when the check was completed. Null if still pending.", "oneOf": [ { "$ref": "#/components/schemas/datetime" }, { "type": "null" } ] }, "check_type": { "$ref": "#/components/schemas/regulated_county_check_type" }, "status": { "$ref": "#/components/schemas/regulated_county_check_status" }, "error_reason": { "$ref": "#/components/schemas/check_error_reason" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "search_criteria": { "$ref": "#/components/schemas/regulated_county_check_search_criteria" }, "results": { "description": "The fully-disclosed results of the regulated county check.\nEmpty array if no records found or if the check is still pending. A record excluded by\nlegal rules never appears here -- see `excluded_records`.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record" } }, "excluded_records": { "description": "Records excluded by legal rules, reduced to an identifier, classification, jurisdiction,\nand per-charge offense classification. Present only when the account's\n`excluded_record_disclosure` setting is `stripped`; omitted (or empty) otherwise, and\nalways separate from `results`.\n", "type": "array", "items": { "$ref": "#/components/schemas/regulated_record_stripped" } }, "run_notes": { "$ref": "#/components/schemas/run_notes" }, "review": { "description": "Present only when `include[]=review` is requested; omitted otherwise.\nNull when no accept/decline/dispute decision exists for this check.\n", "oneOf": [ { "$ref": "#/components/schemas/check_review" }, { "type": "null" } ] }, "adverse_action_enabled": { "description": "Present only when `include[]=review` is requested; omitted otherwise.\nIndicates whether adverse-action workflow is enabled for this product.\n", "type": "boolean" } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "regulated county check with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "regulated county check with profile object" } ] }, "county-check-completed-event-body": { "type": "object", "description": "Emitted when a regulated county check completes and results are available\n(`data.status` is `complete`). The `data` object is the regulated county check resource.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "county_check.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "$ref": "#/components/schemas/regulated_county_check" }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "county-check-not-available-event-body": { "type": "object", "description": "Emitted for a regulated county check when the search cannot be completed and is cancelled\n(e.g. the provider cancels the search). The check reports `data.status` of `cancelled` and\nno records are returned.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "county_check.not_available" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "$ref": "#/components/schemas/regulated_county_check" }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "county_check_request_from_pii": { "description": "Request to create a county check using personally identifiable information (PII).", "type": "object", "properties": { "first_name": { "description": "First name of the person. Required (with last_name) when not sending full_name or using profile_id.", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name of the person.", "type": "string", "example": "Mary" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "Last name of the person. Required (with first_name) when not sending full_name or using profile_id.", "type": "string", "example": "Smith" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\nIf you already know the first and last names, we suggest sending them.\n", "type": "string", "example": "Jane Mary Smith" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nRequired when not using profile_id.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "state": { "description": "The two-letter US state code for the search jurisdiction (county or statewide).", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "lookback_period_in_years": { "description": "Optional number of years to look back for criminal records.\nIf not provided, the default lookback period configured for the account will be used.\n", "type": "integer", "minimum": 1, "maximum": 99, "example": 7 }, "include_null_date_of_birth": { "description": "Optional override for this request indicating whether to include records with a null date of birth.\nIf omitted, your account's default setting is used (or 'true' if not configured).\n", "type": "boolean", "example": true }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "address": { "$ref": "#/components/schemas/address", "description": "{% partial file=\"/_partials/schema-county-check-address-field.md\" /%}\n" }, "addresses": { "description": "{% partial file=\"/_partials/schema-county-check-addresses-field.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. Pass a single-element array if you only have one ruleset to apply.\nNote: county check rulesets do not support `dob_matching_level`, `dob_types_requiring_address_match`, or `source_states`.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } } }, "required": [ "dob", "state", "county_fips_code" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "Jane", "middle_name": "Mary", "last_name": "Smith", "dob": "19900115", "state": "CA", "county_fips_code": "06075", "lookback_period_in_years": 7 } }, "county_check_request_from_profile": { "description": "Create a county check from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request` (`reference_id` may accompany `profile_id`).\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "type": "object", "properties": { "profile_id": { "description": "The unique identifier of an existing profile containing PII.", "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "state": { "description": "The two-letter US state code for the search jurisdiction (county or statewide).", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "lookback_period_in_years": { "description": "Optional number of years to look back for criminal records.\nIf not provided, the default lookback period configured for the account will be used.\n", "type": "integer", "minimum": 1, "maximum": 99, "example": 7 }, "include_null_date_of_birth": { "description": "Optional override for this request indicating whether to include records with a null date of birth.\nIf omitted, your account's default setting is used (or 'true' if not configured).\n", "type": "boolean", "example": true }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. Pass a single-element array if you only have one ruleset to apply.\nNote: county check rulesets do not support `dob_matching_level`, `dob_types_requiring_address_match`, or `source_states`.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } } }, "required": [ "profile_id", "state", "county_fips_code" ], "example": { "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890", "state": "CA", "county_fips_code": "06075", "lookback_period_in_years": 7 } }, "county_check_request_from_case_number": { "description": "Request to create a county check by searching for a specific court case number.\nUse this mode when you have a known case number from a court record instead of subject PII.\n\n`case_number` is mutually exclusive with `first_name`/`last_name`, `dob`, `profile_id`, and `lookback_period_in_years`.\nCase number search is currently supported only in **NC** and **MN**.\n", "type": "object", "properties": { "case_number": { "description": "The court case number to search for. Must contain only letters, numbers, spaces, and hyphens.\nExample NC case number format: `1992CRS000215`\n", "type": "string", "pattern": "^[A-Za-z0-9\\- ]+$", "example": "1992CRS000215" }, "state": { "description": "The two-letter US state code for the search jurisdiction.\nCase number search is supported only for `NC` and `MN`.\n", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "ruleset_ids": { "description": "A list of ruleset identifiers to apply. Pass a single-element array if you only have one ruleset to apply.\nNote: county check rulesets do not support `dob_matching_level`, `dob_types_requiring_address_match`, or `source_states`.\n", "type": "array", "items": { "$ref": "#/components/schemas/ruleset_id" } } }, "required": [ "case_number", "state", "county_fips_code" ], "example": { "case_number": "1992CRS000215", "state": "NC", "county_fips_code": "37063" } }, "county_check_request": { "description": "Request to create a county check. Supports three mutually exclusive search modes:\n- **PII search**: provide `first_name`, `last_name`, and `dob`\n- **Profile search**: provide an existing `profile_id`\n- **Case number search**: provide a court `case_number` (NC and MN only)\n", "oneOf": [ { "$ref": "#/components/schemas/county_check_request_from_pii" }, { "$ref": "#/components/schemas/county_check_request_from_profile" }, { "$ref": "#/components/schemas/county_check_request_from_case_number" } ] }, "county_check_type": { "description": "The type of county check.", "type": "string", "title": "county_check_type", "enum": [ "county_criminal" ], "default": "county_criminal" }, "county_check_status": { "description": "The current status of the county check.\n- `pending` — the check has been submitted and is awaiting results.\n- `complete` — results are available. A `county_criminal.completed` webhook is delivered.\n- `cancelled` — the search was cancelled, either at your request or because it could not\n be completed. When a search cannot be completed, a `county_criminal.not_available` webhook\n is delivered.\n", "type": "string", "title": "county_check_status", "enum": [ "pending", "complete", "cancelled" ], "example": "pending" }, "county_check_search_criteria": { "description": "The search criteria used for the county check. Field presence depends on how the check was submitted:\n\n- **PII or profile search** — includes `first_name`, `last_name`, and usually `date_of_birth`\n (from the request or linked profile). `case_number` is omitted.\n- **Case number search** — includes `case_number`. Name and date-of-birth fields are omitted.\n", "type": "object", "properties": { "first_name": { "description": "First name of the person. Present for PII and profile searches; omitted for case-number searches.", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name of the person. Present for PII and profile searches when supplied; omitted for case-number searches.", "type": "string", "example": "Mary" }, "last_name": { "description": "Last name of the person. Present for PII and profile searches; omitted for case-number searches.", "type": "string", "example": "Smith" }, "date_of_birth": { "description": "Date of birth in the form YYYY-MM-DD. Present for PII and profile searches; omitted for case-number searches.", "allOf": [ { "$ref": "#/components/schemas/date" } ] }, "state": { "description": "The two-letter US state code.", "$ref": "#/components/schemas/state_code" }, "county_fips_code": { "$ref": "#/components/schemas/county_fips_code_or_statewide" }, "lookback_period_in_years": { "description": "The number of years to look back for criminal records. Present for PII and profile searches;\nomitted for case-number searches.\n", "type": "integer", "example": 7 }, "case_number": { "description": "The court case number used for the search. Present only for case-number searches;\nomitted for PII and profile searches.\n", "type": "string", "example": "1992CRS000215" } } }, "county_check": { "type": "object", "description": "A county criminal check response. Case-number searches always return `profile_id: null`.\n", "required": [ "id", "created_at", "check_type", "status", "search_criteria", "results" ], "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "description": "The timestamp when the check was completed. Null if still pending.", "oneOf": [ { "$ref": "#/components/schemas/datetime" }, { "type": "null" } ] }, "check_type": { "$ref": "#/components/schemas/county_check_type" }, "status": { "$ref": "#/components/schemas/county_check_status" }, "error_reason": { "$ref": "#/components/schemas/check_error_reason" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "search_criteria": { "$ref": "#/components/schemas/county_check_search_criteria" }, "results": { "description": "The results of the county check.\nEmpty array if no records found or if the check is still pending.\n", "type": "array", "items": { "$ref": "#/components/schemas/record" } }, "run_notes": { "$ref": "#/components/schemas/run_notes" }, "profile_id": { "description": "Profile UUID when the check is associated with a profile. `null` for case-number searches.\nOmitted when `include[]=profile` is used — use the nested `profile` object instead.\n", "oneOf": [ { "$ref": "#/components/schemas/profile_id" }, { "type": "null" } ] }, "profile": { "description": "Nested profile when `include[]=profile` is requested. Omitted for case-number searches,\nwhich are not associated with a profile.\n", "$ref": "#/components/schemas/profile" } } }, "county-criminal-completed-event-body": { "type": "object", "description": "Emitted when a county criminal check completes and results are available\n(`data.status` is `complete`). The `data` object is the county check resource.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "county_criminal.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "$ref": "#/components/schemas/county_check" }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "county-criminal-not-available-event-body": { "type": "object", "description": "Emitted for a county criminal check when the search cannot be completed and is cancelled\n(e.g. the provider cancels the search). The check reports `data.status` of `cancelled` and\nno records are returned.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "county_criminal.not_available" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "$ref": "#/components/schemas/county_check" }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "county_check_cancel_request": { "description": "Request to cancel a pending county check.", "type": "object", "properties": { "reason": { "description": "The reason for cancelling the county check.", "type": "string", "minLength": 1, "maxLength": 500, "example": "Candidate withdrew application" } }, "required": [ "reason" ], "example": { "reason": "Candidate withdrew application" } }, "criminal_check": { "description": "A criminal check result. Results are only available after the check completes (`completed_at` is set).\nBefore completion, the results array will be empty.\nAlways check `completed_at` before interpreting the `results` array: an empty `results` array is ambiguous unless `completed_at` is set. When `completed_at` is `null` the check is still pending, whereas an empty `results` array with `completed_at` set means the check completed with no records found.\n", "allOf": [ { "$ref": "#/components/schemas/check" }, { "type": "object", "properties": { "completed_at": { "description": "Timestamp when the check completed and results became available via GET (and webhook, if configured).\n`null` while the check is still pending.\n" }, "results": { "description": "Array of criminal **records**. An empty array is ambiguous unless `completed_at` is set:\nwhen `completed_at` is `null` the check is still pending, whereas an empty array with\n`completed_at` set means the check completed with no records found.\n\n**Confidence scoring:** Each record's `cases[]` entries may include `identity_match_confidence_level`,\nsummarizing identity-match confidence for that case. See the `case` schema and the Instant Criminal Checks tag description.\nEach **record** may separately include `record_match_confidence_level`, summarizing how strongly that whole record aligns\nwith the identity it was matched to (high, medium, or low), measured independently from the case-level\n`identity_match_confidence_level`. See the `record` schema in the checks component.\n" } } } ] }, "criminal-check-request-from-pii-base": { "type": "object", "properties": { "input_type": { "$ref": "#/components/schemas/input_type" }, "dob": { "description": "Date of birth in the form YYYYMMDD.\nMust be a valid date and cannot be in the future.\nIf invalid, the API returns a 400 with a `validation_error` pointing to `/dob`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "description": "Social Security Number used for additional identity verification and record matching", "$ref": "#/components/schemas/ssn_string" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "addresses": { "description": "{% partial file=\"/_partials/schema-check-addresses-field-criminal-search.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" }, "order_by": { "$ref": "#/components/schemas/order_by" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "allow_duplicate_criminal_records": { "$ref": "#/components/schemas/check_request_allow_duplicate_criminal_records" } } }, "criminal-check-request-from-pii": { "description": "Request to create a new criminal check using PII.\nUse **first_name + last_name** (optional **middle_name**) **or** a single **full_name** string, but not both.\n", "allOf": [ { "type": "object", "properties": { "first_name": { "description": "First name (given name). Do not include prefixes such as \"Ms.\" or \"Dr.\"\n", "type": "string", "example": "Jane" }, "middle_name": { "description": "Middle name(s). Optional.", "type": "string", "example": "Mary Louise" }, "last_name": { "description": "Last name (surname). Do not include suffixes such as \"Jr.\" or \"2nd\".\n", "type": "string", "example": "O'Donnell-Van Helsing" }, "full_name": { "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name,\nand then use those for the check. With `no_middle_name: true`, any parsed middle token is folded\ninto the last name instead of being stored as a middle name.\nIf you already know the first and last names, we suggest sending them.\nThe parser will attempt to remove prefixes and suffixes, and handles several different formats of name,\nbut we cannot guarantee it will parse the name in the manner you expect.\n", "type": "string", "example": "O'Donnell-Van Helsing, Dr. Jane Mary Louise, MD" } } }, { "$ref": "#/components/schemas/criminal-check-request-from-pii-base" }, { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "JOHN", "last_name": "SMITH", "dob": "19900101", "ssn": "123-45-6789", "phone": "+14155552671", "addresses": [ { "street": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip_code": "90001" } ] } }, "criminal-check-request-from-profile": { "description": "Create a criminal check from an existing profile. Do not include inline PII or address fields alongside `profile_id`—the API rejects combined requests with `400 Bad Request` (`reference_id` may accompany `profile_id`).\nNote: check_type is automatically set to 'criminal_check' and cannot be specified.\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "type": "object", "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "input_type": { "$ref": "#/components/schemas/input_type" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "source_states": { "$ref": "#/components/schemas/source_states" }, "order_by": { "$ref": "#/components/schemas/order_by" }, "allow_duplicate_criminal_records": { "$ref": "#/components/schemas/check_request_allow_duplicate_criminal_records" } }, "required": [ "profile_id" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080" } }, "criminal-check-completed-event-body": { "type": "object", "description": "Emitted when a criminal check completes. The embedded `data.profile` object does not\ninclude an `ssn` field — SSN is intentionally omitted from webhook payloads.\n", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "criminal_check.completed" ] }, "created_at": { "$ref": "#/components/schemas/datetime" }, "data": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "results": { "description": "When there are no results found, this will be an empty array.", "type": "array", "items": { "$ref": "#/components/schemas/record" } }, "profile": { "description": "The profile associated with this check. The `ssn` field is not present in webhook payloads.", "$ref": "#/components/schemas/profile" }, "check_type": { "type": "string", "enum": [ "criminal_check" ] }, "input_type": { "$ref": "#/components/schemas/input_type" }, "reference_id": { "$ref": "#/components/schemas/reference_id" } } }, "account_id": { "$ref": "#/components/schemas/uuid" } }, "required": [ "id", "object", "type", "created_at", "data", "account_id" ] }, "matched_profile_limit": { "description": "Maximum number of matched profiles to return in `results`, ranked by identity match strength\n(best first). Send `1` when you only want the single best identity match; raise it to review\nseveral candidate identities. This limits profiles only -- each returned profile still carries\nall of its records.\n", "type": "integer", "minimum": 1, "maximum": 20, "default": 10, "example": 5 }, "profile_score_threshold": { "description": "Overrides, for this request only, the minimum identity-match score a matched profile must meet\nto be included in `results`. Profiles scoring below this value are excluded from the response.\n\nWhen omitted, the account's configured minimum score is used. Send `0` to disable score-based\nfiltering entirely and review every matched profile our identity provider returned, regardless\nof score.\n", "type": "number", "minimum": 0, "maximum": 1, "example": 0 }, "profile_criminal_check_request_from_pii": { "description": "Create a profile criminal check using inline PII.", "type": "object", "properties": { "first_name": { "description": "first name (given name). Do not include prefixes, like \"Ms.\" or \"Dr.\"", "type": "string", "example": "Marcus" }, "middle_name": { "description": "middle name(s)", "type": "string" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "description": "last name (surname). Do not include suffixes, like \"Jr.\" or \"2nd\".", "type": "string", "example": "Williams" }, "full_name": { "description": "Either send the full name, or first and last names, but not both. If you send a full name,\nCheckr will attempt to parse it into first name, middle name(s), and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\n", "type": "string" }, "dob": { "description": "Date of birth in the form YYYYMMDD. Not required by this schema, but in practice a search\nwithout a date of birth cannot be satisfied by our identity provider today and returns\n`400 provider_error`.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "$ref": "#/components/schemas/ssn_string" }, "phone": { "$ref": "#/components/schemas/phone_string" }, "email": { "$ref": "#/components/schemas/email_string" }, "driver_license_number": { "type": "string", "description": "Driver license number. Format depends on the issuing state. Send this **together with**\n`driver_license_state` or not at all: the two are combined into a single\n`JURISDICTION:LICENSE` value before being matched, so a number sent without a state is\nmatched as a different value and will silently fail to find the driver it identifies.\n", "example": "D1234567" }, "driver_license_state": { "$ref": "#/components/schemas/state_code", "description": "State that issued the driver license. Required whenever `driver_license_number` is sent\n(see that field). Unlike driver license status checks, this is not restricted to states\nwith DMV data-access agreements -- any US state or protectorate is accepted.\n" }, "custom_id": { "$ref": "#/components/schemas/custom_id_string" }, "address": { "$ref": "#/components/schemas/address", "description": "{% partial file=\"/_partials/schema-inline-address-persistence-singular-or-plural.md\" /%}\n" }, "addresses": { "$ref": "#/components/schemas/addresses", "description": "{% partial file=\"/_partials/schema-inline-address-persistence-singular-or-plural.md\" /%}\n" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "limit": { "$ref": "#/components/schemas/matched_profile_limit" }, "score_threshold": { "$ref": "#/components/schemas/profile_score_threshold" } }, "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "Marcus", "last_name": "Williams", "dob": "19880315" } }, "profile_criminal_check_request_from_profile": { "description": "Create a profile criminal check from an existing profile. Do not include inline PII fields\nalongside `profile_id` -- the API rejects combined requests with `400 Bad Request`.\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "type": "object", "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "ruleset_id": { "$ref": "#/components/schemas/ruleset_id" }, "ruleset_ids": { "$ref": "#/components/schemas/ruleset_ids" }, "limit": { "$ref": "#/components/schemas/matched_profile_limit" }, "score_threshold": { "$ref": "#/components/schemas/profile_score_threshold" } }, "required": [ "profile_id" ] }, "profile_criminal_check_status": { "description": "The current status of the profile criminal check. This is the only field that separates a search\nthat **failed** from one that ran and had nothing to report -- `completed_at`, `results_info` and\n`results` look identical in both cases.\n\n`null` on checks created before this field was introduced. A `null` status is not an error:\nthose checks did run, so read `completed_at` and `results_info` to tell whether one finished.\n", "type": [ "string", "null" ], "title": "profile_criminal_check_status", "enum": [ "pending", "complete", "error", null ], "example": "complete", "x-enumDescriptions": { "pending": "The search has been submitted and is awaiting results. Rare for this product, which completes synchronously on create.", "complete": "The search ran and `results` is authoritative. An empty `results` array here means the search had nothing to return -- either no identity matched, or every matched identity scored below the effective minimum match score (see `results` for the distinction).", "error": "The search could not be completed, so `results` is empty because nothing was searched, **not** because nothing was found. `completed_at` is `null`. Treat this as \"no answer\", never as a clear result." } }, "profile_criminal_check_type": { "type": "string", "enum": [ "profile_criminal_check" ] }, "profile_match_confidence_level": { "description": "**Identity match confidence** for this matched profile, based on how strongly the identity\nmatched by our people data graph aligns with the PII you submitted for the check.\n\nThe values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.\n\nThis is measured independently from each record's own `record_match_confidence_level` and from each\ncase's `identity_match_confidence_level` (see the `record`/`case` schema) -- a profile-level \"high\",\na record-level \"high\", and a case-level \"high\" are not derived from the same measurement and should\nnot be compared to each other.\n", "type": "string", "enum": [ "high", "medium", "low" ], "example": "high", "x-enumDescriptions": { "high": "Strong identity alignment with the searched subject.", "medium": "Moderate alignment with the searched subject.", "low": "Weak alignment with the searched subject." } }, "name_variation": { "type": "object", "description": "One name variation on file for the matched profile.", "properties": { "full_name": { "type": "string", "example": "Marcus G Williams" }, "first_name": { "type": "string", "example": "Marcus" }, "middle_name": { "type": "string", "example": "G" }, "last_name": { "type": "string", "example": "Williams" } } }, "profile_deceased": { "description": "Whether the sources linked to this matched profile have reported the person as deceased, and\nthe date or dates of death they gave.\n", "type": "object", "required": [ "status" ], "properties": { "status": { "description": "The resolved answer across all sources linked to this profile.", "type": "string", "enum": [ "deceased", "not_deceased", "conflict", "no_data" ], "example": "not_deceased", "x-enumDescriptions": { "deceased": "Every source that spoke reported the person as deceased, with no inconsistencies.", "not_deceased": "Every source that spoke explicitly reported the person as **not** deceased.", "conflict": "An inconsistency was detected and could not be reconciled. This does **not** necessarily mean sources disagreed about whether the person is deceased -- it can also mean a single source contradicted itself, for example by supplying a date of death that falls before its own date of birth for the same person. Treat `conflict` as \"do not rely on this signal without review,\" not as a reported death.", "no_data": "No linked source has made any assertion either way. **This does not mean the person is alive** -- that is `not_deceased`, which requires a source to affirmatively report the person as living. Treating the two as equivalent will overstate what the data says." } }, "dates_of_death": { "description": "Dates of death reported by the sources linked to this profile.", "type": "array", "items": { "$ref": "#/components/schemas/date_string_partial" }, "example": [ "19630800" ] } } }, "matched_profile_identity": { "description": "A conservative identity summary for the matched profile. This summary intentionally does not\ninclude raw contact PII (emails, phone numbers) or document numbers, even when the underlying\nidentity provider carries them -- that exclusion applies only to this identity summary, not to\nthe matched profile's nested `records[]`, which may legitimately include a `doc_number` as\ncourt-record data (see the `record` schema).\n", "type": "object", "properties": { "name_variations": { "description": "Name variations on file for this identity, most authoritative first, capped at 10 entries.\n", "type": "array", "items": { "$ref": "#/components/schemas/name_variation" } }, "dates_of_birth": { "description": "Dates of birth on file for this identity.", "type": "array", "items": { "$ref": "#/components/schemas/date_string_partial" } }, "gender": { "type": "string", "enum": [ "male", "female", "non_binary", "other" ], "example": "male" }, "states": { "description": "US states associated with this identity's addresses on file.", "type": "array", "items": { "$ref": "#/components/schemas/state_code" }, "example": [ "FL", "GA" ] }, "photo_urls": { "description": "A set of URLs referencing photos of this person: photos on file for this identity, plus\nany photos attached to this matched profile's returned `records[]` (for example, a\ncriminal record's mugshot). Only records visible in `records[]` contribute here -- a\nrecord filtered out of the response never adds a photo to this list. Deduplicated, capped\nat 20 entries. Same field name and shape as Instant Criminal Checks'\n`record.person.photo_urls`.\n", "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://example.com/pictures/marcus-selfie.jpg" ] }, "deceased": { "$ref": "#/components/schemas/profile_deceased" } } }, "matched_profile": { "description": "A single identity matched by the search, with its own nested criminal records. A check's\n`results` array may contain zero, one, or more matched profiles. Matched profiles are not\nindividually identifiable -- refer to them by their position in the `results` array (for\nexample, \"the 1st match\" or \"the 5th match\").\n", "type": "object", "properties": { "match_confidence_level": { "$ref": "#/components/schemas/profile_match_confidence_level" }, "identity": { "$ref": "#/components/schemas/matched_profile_identity" }, "records": { "description": "Criminal records associated with this matched profile. Same shape as the Instant Criminal Checks `record` schema.", "type": "array", "items": { "$ref": "#/components/schemas/record" } } } }, "profile_criminal_check": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "status": { "$ref": "#/components/schemas/profile_criminal_check_status" }, "check_type": { "$ref": "#/components/schemas/profile_criminal_check_type" }, "input_type": { "description": "Always `person` for this product -- profile_criminal_check has no address-based search path.", "allOf": [ { "$ref": "#/components/schemas/input_type" } ] }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "results_info": { "type": "object", "properties": { "profiles_returned": { "description": "Count of matched-profile entries in `results` that have at least one visible record --\nnot simply `results.length`, since `results` may also include matched identities with\nan empty `records` array (see `results` below). Capped by the request's `limit` (or its\ndefault/max), and reduced further by any ruleset applied on the request: a profile no\nlonger counts toward this total once all of its records are excluded by the ruleset,\neven though the profile itself still appears in `results`.\n", "type": "integer", "minimum": 0 }, "profiles_limit": { "description": "The limit this search actually ran under -- the request's `limit`, echoed back.\n", "allOf": [ { "$ref": "#/components/schemas/matched_profile_limit" } ] }, "profiles_truncated": { "description": "When `true`, this search matched more profiles than the requested `limit`, and\n`results` holds the highest-scoring ones. A more specific search -- adding a date of\nbirth, a state, or an SSN -- is a way to bring the identity you are looking for into\nrange.\n", "type": "boolean" } } }, "results": { "description": "Array of matched identities (profiles), each with its own nested records. Empty array when\nno identity matched at all, or when every matched identity scored below the effective\nminimum match score (the account's configured minimum, or this request's `score_threshold`\noverride) -- a below-threshold match is excluded entirely, not included with `records: []`.\nA matched profile that clears the score threshold but has all of its records excluded (by a\nruleset applied on the request, or by de-duplication) still appears here, with `records` as\nan empty array -- the identity match itself remains reportable even when nothing survived\nfiltering. Sorted by `match_confidence_level`'s underlying score, descending -- the best\nmatch is always first. Capped at the request's `limit` (default 10, max 20). This ordering\nis a stable contract you can rely on: matched profiles are not otherwise individually\nidentifiable (no `profile_id` is exposed), so position in this array is the only way to\nrefer to a specific match (e.g. \"the 1st match\").\n", "type": "array", "items": { "$ref": "#/components/schemas/matched_profile" } } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "profile criminal check with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "profile criminal check with profile object" } ] }, "eviction_subject": { "title": "eviction_subject", "type": "object", "description": "Identity information for the subject of the eviction record, as reported by the data provider.", "properties": { "full_name": { "type": [ "string", "null" ], "description": "Full name of the subject as recorded on the eviction record.", "example": "Patricia Ann Holloway" }, "dob": { "type": [ "string", "null" ], "description": "Date of birth of the subject in ISO 8601 format (`YYYY-MM-DD`), if available.", "example": "1985-03-14" }, "address": { "type": [ "string", "null" ], "description": "Address of the subject as recorded on the eviction record.", "example": "482 Birch Lane, Springfield, IL 62704" }, "aliases": { "type": [ "string", "null" ], "description": "Known aliases or alternate names for the subject, as reported by the data provider.", "example": "P. Holloway" }, "state": { "type": [ "string", "null" ], "description": "State associated with the subject record.", "example": "IL" }, "jurisdiction": { "type": [ "string", "null" ], "description": "Jurisdiction in which the eviction record originates.", "example": "Sangamon County" }, "source": { "type": [ "string", "null" ], "description": "Data source identifier for the record, as assigned by the data provider.", "example": "IL_SANG_EVICT" }, "case_number": { "type": [ "string", "null" ], "description": "Case number as recorded on the subject record.", "example": "2023-EV-004471" }, "category": { "type": [ "string", "null" ], "description": "Match category assigned by the data provider (e.g. the type of match or record classification).", "example": "Eviction" }, "status": { "type": [ "string", "null" ], "description": "Status of the subject record as reported by the data provider.", "example": "Active" }, "comments": { "type": [ "string", "null" ], "description": "Free-text comments associated with the subject record, if any.", "example": null } } }, "eviction_plaintiff": { "title": "eviction_plaintiff", "type": "object", "description": "Information about the plaintiff in the eviction case.", "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the plaintiff (typically the landlord or property management company).", "example": "Riverstone Property Management LLC" }, "phone": { "type": [ "string", "null" ], "description": "Phone number of the plaintiff.", "example": "217-555-0182" }, "attorney": { "type": [ "string", "null" ], "description": "Name of the plaintiff's attorney, if represented.", "example": "Gregory L. Marsh" }, "attorney_phone": { "type": [ "string", "null" ], "description": "Phone number of the plaintiff's attorney.", "example": "217-555-0199" } } }, "eviction_judgement": { "title": "eviction_judgement", "type": "object", "description": "Details of the judgement rendered in the eviction case.", "properties": { "date": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the judgement was entered, in ISO 8601 format (`YYYY-MM-DD`).", "example": "2023-07-05" }, "amount_cents": { "type": [ "integer", "null" ], "description": "Monetary amount of the judgement in cents (e.g. `250000` = $2,500.00). Null if no monetary judgement.", "example": 347500 }, "type": { "type": [ "string", "null" ], "description": "Type of judgement as reported by the court (format varies by jurisdiction).", "example": "Judgment for Plaintiff" }, "for": { "type": [ "string", "null" ], "description": "Party in whose favor the judgement was rendered.", "example": "Plaintiff" }, "satisfaction_amount_cents": { "type": [ "integer", "null" ], "description": "Amount in cents by which the judgement has been satisfied. Null if not satisfied.", "example": null }, "release_date": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the judgement was released or satisfied, in ISO 8601 format (`YYYY-MM-DD`). Null if not yet released.", "example": null } } }, "eviction_case": { "title": "eviction_case", "type": "object", "description": "Court filing and judgement details for the eviction case.", "properties": { "court": { "type": [ "string", "null" ], "description": "Name of the court where the eviction case was filed.", "example": "Sangamon County Circuit Court" }, "case_number": { "type": [ "string", "null" ], "description": "Case number assigned by the court.", "example": "2023-EV-004471" }, "filing_date": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the eviction case was filed, in ISO 8601 format (`YYYY-MM-DD`).", "example": "2023-06-12" }, "notice_type": { "type": [ "string", "null" ], "description": "The type of eviction notice that was filed (e.g. `\"Unlawful Detainer\"`, `\"Forcible Entry and Detainer\"`, `\"Pay or Quit\"`).\nFormat varies by jurisdiction.\n", "example": "Forcible Entry and Detainer" }, "agency_state": { "type": [ "string", "null" ], "description": "Two-letter state code of the agency that handled the case.", "example": "IL" }, "agency_county": { "type": [ "string", "null" ], "description": "County of the agency that handled the case.", "example": "Sangamon" }, "dismissal_date": { "type": [ "string", "null" ], "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the case was dismissed, in ISO 8601 format (`YYYY-MM-DD`). Null if not dismissed.", "example": null }, "default_judgement": { "type": "boolean", "description": "Whether the judgement was entered by default — i.e. the defendant did not appear or respond.", "example": true }, "restored_premises": { "type": "boolean", "description": "Whether the premises were restored (returned) to the plaintiff following the judgement.", "example": false }, "plaintiff": { "$ref": "#/components/schemas/eviction_plaintiff" }, "judgement": { "$ref": "#/components/schemas/eviction_judgement" } } }, "eviction_result": { "title": "eviction_result", "type": "object", "description": "A single matched candidate record from an eviction search.", "properties": { "first_name": { "type": "string", "description": "First name of the matched candidate.", "example": "Patricia" }, "last_name": { "type": "string", "description": "Last name of the matched candidate.", "example": "Holloway" }, "middle_name": { "type": [ "string", "null" ], "description": "Middle name of the matched candidate, if available.", "example": "Ann" }, "address": { "type": [ "string", "null" ], "description": "Street address associated with the matched candidate.", "example": "482 Birch Lane" }, "city": { "type": [ "string", "null" ], "description": "City associated with the matched candidate.", "example": "Springfield" }, "state": { "type": [ "string", "null" ], "description": "Two-letter state code associated with the matched candidate.", "example": "IL" }, "zip_code": { "type": [ "string", "null" ], "description": "ZIP code associated with the matched candidate.", "example": "62704" }, "zone": { "type": [ "string", "null" ], "description": "The geographic search zone that produced this match.\nTypically corresponds to a metropolitan area, county, or regional search boundary used by the data provider.\n", "example": "Springfield Metro" }, "subject": { "$ref": "#/components/schemas/eviction_subject" }, "case": { "$ref": "#/components/schemas/eviction_case" } } }, "eviction_check": { "type": "object", "description": "An eviction check and its results.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "completed_at": { "$ref": "#/components/schemas/datetime" }, "reference_id": { "$ref": "#/components/schemas/reference_id" }, "results": { "description": "Array of matched candidate records. Each item represents one person matched against the search inputs.\nWhen no eviction records are found, this will be an empty array.\n", "type": "array", "items": { "$ref": "#/components/schemas/eviction_result" } }, "run_notes": { "description": "An unstructured array of human-readable notes about this particular check.\nMay contain notes about how input was parsed or other information about results.\nNot intended to be parsed by computer, as these notes are not guaranteed to be in any given format.\n", "type": "array", "items": { "type": "string", "example": "changed last_name from 'Smith Jr' to 'Smith'" } } }, "oneOf": [ { "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" } }, "title": "eviction check with profile id" }, { "properties": { "profile": { "$ref": "#/components/schemas/profile" } }, "title": "eviction check with profile object" } ] }, "property_zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$", "description": "ZIP code of the property being evaluated. When provided, eviction records are\nfiltered to those reportable under FCRA for that property location.\n", "example": "62704" }, "eviction-check-request-from-pii": { "type": "object", "description": "Create an eviction check by providing PII directly. Provide either `full_name`, or both `first_name` and `last_name` (not both). `ssn`, `addresses`, and `permissible_purpose` are also required.\n", "properties": { "first_name": { "type": "string", "description": "First name (given name). Do not include prefixes like \"Ms.\" or \"Dr.\"", "example": "Patricia" }, "middle_name": { "type": "string", "description": "Middle name(s).", "example": "Ann" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "last_name": { "type": "string", "description": "Last name (surname). Do not include suffixes like \"Jr.\" or \"2nd\".", "example": "Holloway" }, "full_name": { "type": "string", "description": "Either send the full name, or first, middle (optional), and last names, but not both.\nIf you send a full name, we will attempt to parse it into first name, middle name(s) and last name.\nWith `no_middle_name: true`, any parsed middle token is folded into the last name instead of\nbeing stored as a middle name.\nIf you already know the first and last names, we suggest sending them.\n", "example": "Patricia Ann Holloway" }, "dob": { "description": "Date of birth in `YYYYMMDD` format. Strongly encouraged — providing a DOB significantly reduces false positives.\nMust be a valid date and cannot be in the future.\n", "allOf": [ { "$ref": "#/components/schemas/date_string_complete" } ] }, "ssn": { "description": "Social Security Number. Required to run an eviction search.", "allOf": [ { "$ref": "#/components/schemas/ssn_string" } ] }, "addresses": { "description": "{% partial file=\"/_partials/schema-eviction-addresses-field-inline.md\" /%}\n", "$ref": "#/components/schemas/addresses" }, "property_zip": { "$ref": "#/components/schemas/property_zip" }, "permissible_purpose": { "description": "The permissible purpose for requesting this eviction check, as required by the Fair Credit Reporting Act (FCRA).\nThis must be provided for all regulated eviction checks to ensure compliance with federal regulations.\n", "allOf": [ { "$ref": "#/components/schemas/permissible_purpose" } ] }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "required": [ "ssn", "addresses", "permissible_purpose" ], "allOf": [ { "$ref": "#/components/schemas/name_full_or_split_required" }, { "$ref": "#/components/schemas/middle_name_no_middle_name_exclusive" } ], "example": { "first_name": "Patricia", "last_name": "Holloway", "dob": "19850314", "ssn": "123-45-6789", "permissible_purpose": "Employment", "addresses": [ { "street": "482 Birch Lane", "city": "Springfield", "state": "IL", "zip_code": "62704" } ] } }, "eviction-check-request-from-profile": { "type": "object", "description": "Create an eviction check from an existing profile. Do not include inline name/identity fields (`first_name`, `dob`, `ssn`, etc.) alongside `profile_id`—the API rejects combined requests with `400 Bad Request`. `addresses` and `permissible_purpose` (both required), plus `property_zip`, `reference_id`, and `no_middle_name`, may accompany `profile_id`.\nThe profile must have an SSN on record — it is required to run an eviction search.\nIf `no_middle_name` is provided, it is persisted to the referenced profile, updating\nany previously stored value.\n", "properties": { "profile_id": { "$ref": "#/components/schemas/profile_id" }, "no_middle_name": { "$ref": "#/components/schemas/no_middle_name" }, "addresses": { "description": "An array of addresses associated with the person. Required — at least\none address is needed to scope the eviction search. Addresses stored on\nthe profile are not used as a fallback and must be explicitly provided\nin the request.\n", "$ref": "#/components/schemas/addresses" }, "property_zip": { "$ref": "#/components/schemas/property_zip" }, "permissible_purpose": { "description": "The permissible purpose for requesting this eviction check, as required by the Fair Credit Reporting Act (FCRA).\nThis must be provided for all regulated eviction checks to ensure compliance with federal regulations.\n", "allOf": [ { "$ref": "#/components/schemas/permissible_purpose" } ] }, "reference_id": { "$ref": "#/components/schemas/reference_id" } }, "required": [ "profile_id", "addresses", "permissible_purpose" ], "example": { "profile_id": "014f2478-fc46-46d3-9f1a-b9641e1aa080", "permissible_purpose": "Employment", "addresses": [ { "street": "482 Birch Lane", "city": "Springfield", "state": "IL", "zip_code": "62704" } ] } }, "test_scenario": { "type": "object", "description": "A single deterministic mock scenario available to a test account, describing both the inputs\nthat trigger it and what the resulting response represents.\n", "properties": { "slug": { "description": "Stable identifier for the scenario. Safe to hard-code in your own test suite — slugs do\nnot change once published.\n", "type": "string", "example": "county_michael_doe" }, "products": { "description": "The products this scenario applies to, restricted to the ones enabled on your account.\nSome scenarios back several products at once, but this only ever lists products you can\nactually call — so every value here is safe to use. When the request includes a `product`\nfilter, this contains only that product.\n", "type": "array", "items": { "type": "string" }, "example": [ "county_criminal", "county_criminal_regulated" ] }, "title": { "description": "Short label identifying the scenario.", "type": "string", "example": "Single misdemeanor conviction" }, "description": { "description": "What the response represents — the scenario a customer would encounter in real results.\n", "type": "string", "example": "One misdemeanor DUI record in Cook County, Illinois with a FINDING OF GUILTY disposition, fines and probation." }, "result_kind": { "description": "Coarse classification of the outcome, for grouping and filtering. Deliberately broad:\nproducts are not homogeneous (document verification returns accept/reject, driver license\nstatus returns valid/invalid, PII validation returns a score), so anything more specific\nwould not apply across products. Read `description` for the detail.\n\nNote this describes the shape of the mock *response*, not an adjudication of the subject.\n * `no_records` — completes successfully with an empty result set\n * `records_found` — completes successfully with one or more records\n * `not_found` — the subject or identity could not be resolved\n * `error` — terminates in an error state\n * `cancelled` — terminates as cancelled, firing a not-available webhook\n * `pending` — remains pending for an extended period\n", "type": "string", "enum": [ "no_records", "records_found", "not_found", "error", "cancelled", "pending" ] }, "tags": { "description": "Optional labels describing what the scenario is useful for exercising, for example\n`async_webhook`, `fcra_filtering`, `identity_matching` or `failure`.\n", "type": "array", "items": { "type": "string" }, "example": [ "identity_matching" ] }, "inputs": { "description": "The request fields to send in order to trigger this scenario. Field names match the\nrequest body of the relevant product endpoint. Send every field listed here: some are\nrequired for validation, or are compared against the fixture during identity matching,\neven when they do not select the scenario (see `match_keys`).\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "first_name": "Michael", "last_name": "Doe", "dob": "19850505", "state": "IL", "county_fips_code": "17031" } }, "match_keys": { "description": "The subset of `inputs` that actually selects this scenario. Any input not listed here is\nstill required by the endpoint but does not change which scenario you get.\n\nThis distinction matters most for county checks: the fixture is chosen by name, but the\n`dob` you send is then compared against the date of birth on each fixture record. Send a\ndifferent `dob` and the check still completes — with an empty result set.\n", "type": "array", "items": { "type": "string" }, "example": [ "first_name", "last_name" ] }, "notes": { "description": "Additional guidance for using this scenario, when there is any.", "type": "string", "example": "Send `score_threshold: 0` to see both profiles." } } } }, "responses": { "post-token-response-body": { "description": "OK — Auth0 issued an access token. Use `access_token` as\n`Authorization: Bearer ` on subsequent API calls.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/token" } } } }, "post-token-unauthorized-response-body": { "description": "Unauthorized — client credentials were rejected or the token request failed\nupstream. Body is Auth0's OAuth error object (not the JSON:API error array\nused elsewhere in this API).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth_token_error" } } } }, "error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "rate-limit-exceeded": { "description": "Too Many Requests - the product configuration has reached its usage limit or product access has expired.\nWhen usage limits are configured, the response includes X-RateLimit-* headers (see below).\n", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of API calls allowed for this product configuration.", "schema": { "type": "string", "example": "100" } }, "X-RateLimit-Remaining": { "description": "Number of calls remaining in the current limit period.", "schema": { "type": "string", "example": "0" } }, "X-RateLimit-Expires": { "description": "ISO 8601 timestamp after which product access expires (present only when access_expires_at is set).", "schema": { "type": [ "string", "null" ], "format": "date-time" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "reverse-phone-no-info": { "description": "No info available for this phone number" } }, "requestBodies": { "post-profile-request-body": { "description": "The request body for creating a new profile", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/profile_request_from_pii" }, { "$ref": "#/components/schemas/profile_request_from_address" }, { "$ref": "#/components/schemas/profile_request_from_profile" } ] } } } }, "post-check-request-body": { "description": "The request body for creating a new check.\n\nUse either inline PII/address fields or `profile_id`—not both. See the POST `/checks` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/check-request-from-pii" }, { "$ref": "#/components/schemas/check-request-from-address" }, { "$ref": "#/components/schemas/check-request-from-profile" } ] } } } }, "post-profile-criminal-check-request-body": { "description": "The request body for creating a new profile criminal check.\n\nUse either inline PII fields or `profile_id`—not both. See the POST `/profile_criminal_checks` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/profile_criminal_check_request_from_pii" }, { "$ref": "#/components/schemas/profile_criminal_check_request_from_profile" } ] } } } }, "post-regulated-check-request-body": { "description": "The request body for creating a new regulated check with legal annotation.\n\nUse either inline PII (`addresses[]` only) or `profile_id`—not both. See the POST `/regulated/checks` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/regulated_check_request_from_pii" }, { "$ref": "#/components/schemas/regulated_check_request_from_profile" } ] } } } }, "post-identity-verification-request-body": { "description": "The request body for creating a new identity verification.\n\nUse either inline PII/address fields or `profile_id`—not both. See the POST `/identity_verifications` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/identity-verification-request-from-pii" }, { "$ref": "#/components/schemas/identity-verification-request-from-profile" }, { "$ref": "#/components/schemas/identity-verification-request-from-phone" } ] } } } }, "post-driver-check-request-body": { "description": "The request to create a driver check.\n\nUse either inline PII/address fields or `profile_id`—not both. See the POST `/driver_checks` operation for details.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/driver-check-request-from-pii" }, { "$ref": "#/components/schemas/driver-check-request-from-profile" } ] } } } }, "post-county-check-request-body": { "description": "The request body for creating a county check", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/county_check_request" } } } }, "post-regulated-county-check-request-body": { "description": "The request body for creating a regulated county check", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/regulated_county_check_request" } } } }, "post-county-check-cancel-request-body": { "description": "The request body for cancelling a county check", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/county_check_cancel_request" } } } }, "post-regulated-criminal-report-request-body": { "description": "The request body for creating a new regulated criminal report.\nResults are delivered asynchronously via webhook.\n\nUse either inline PII/address fields or `profile_id`—not both (`reference_id` may accompany `profile_id`). See the POST `/regulated/criminal_reports` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/criminal_report_request_from_pii" }, { "$ref": "#/components/schemas/criminal_report_request_from_profile" } ] } } } }, "post-criminal-check-request-body": { "description": "The request body for creating a new criminal check.\nResults become available via GET once the check completes. When a webhook is configured, they are also delivered asynchronously.\n\nUse either inline PII/address fields or `profile_id`—not both (`reference_id` may accompany `profile_id`). See the POST `/criminal_checks` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/criminal-check-request-from-pii" }, { "$ref": "#/components/schemas/criminal-check-request-from-profile" } ] } } } }, "post-regulated-eviction-check-request-body": { "description": "The request body for creating a new regulated eviction check.\n\nUse either inline name/identity fields or `profile_id`—not both (`addresses`, `property_zip`, and `reference_id` may accompany `profile_id`). See the POST `/regulated/eviction_checks` operation for details.\n", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/eviction-check-request-from-pii" }, { "$ref": "#/components/schemas/eviction-check-request-from-profile" } ] } } } }, "post-token-request-body": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "example": "your-client-id" }, "client_secret": { "type": "string", "example": "your-client-secret" }, "grant_type": { "type": "string", "enum": [ "client_credentials" ], "example": "client_credentials", "description": "OAuth 2.0 grant type. If omitted, client_credentials is assumed. Any other value is rejected." }, "scope": { "type": "string", "example": "read:account create:account", "description": "Optional. Ignored; scopes are assigned from the client configuration." } }, "required": [ "client_id", "client_secret" ] } } } } }, "securitySchemes": { "get-bearer-token-using-oauth2": { "type": "oauth2", "description": "Machine-to-machine (M2M) OAuth 2.0 **client credentials** flow.\n\n1. Exchange your `client_id` and `client_secret` at\n [`POST /accounts/token`](#operation/post-accounts-token)\n (see [Authentication](./index.md#authentication)).\n2. Call protected endpoints with `Authorization: Bearer `.\n\nAccess tokens are JWTs. Lifetime is returned as `expires_in` (typically 24 hours).\nRequest a new token when the current one expires — there is no refresh-token\ngrant on this public token endpoint.\n", "flows": { "clientCredentials": { "tokenUrl": "https://api.checkrtrust.com/v1/accounts/token", "scopes": { "read:account": "Read a single account", "create:account": "Create an account", "delete:account": "Delete an account", "read:users": "List users", "create:user": "Create / invite a user", "read:user": "Read a single user", "update:user": "Update a user", "delete:user": "Delete a user", "read:role": "Read Auth0 role metadata for a user", "update:role": "Assign Auth0 roles to a user", "delete:role": "Remove Auth0 roles from a user" } } } } } } }