Skip to content

Create criminal check

Request

Create a new criminal check. The check runs synchronously but results are only delivered via webhook.

Profile vs inline PII: Submit either a profile_id or inline PII/address fields—not both. Combining profile_id with name fields, address, addresses, or other PII returns 400 Bad Request (validation_error: "request must only contain a profile_id, or other fields"). reference_id may be sent alongside profile_id. Empty address: {} or addresses: [] count as supplied address parameters and cannot be paired with profile_id.

Important Notes:

  • Results are NOT returned in the HTTP response (returns 202 Accepted)
  • Results are delivered asynchronously via webhook
  • Webhook destination_url must be configured in product configuration
Security
get-bearer-token-using-oauth2
Query
include[]Array of strings

Embed the profile in the response in place of profile_id.

Items ValueDescription
profile

Embeds the full profile object in place of profile_id.

Examples:
Single value
include[]=["profile"]
Bodyapplication/jsonrequired

The request body for creating a new criminal check. Results are delivered asynchronously via webhook.

Use either inline PII/address fields or profile_id—not both (reference_id may accompany profile_id). See the POST /criminal_checks operation for details.

One of:

Request to create a new criminal check using PII. Use first_name + last_name (optional middle_name) or a single full_name string, but not both.

One of:

Provide first_name and last_name (without full_name).

object(name-parts)
POST
/criminal_checks
curl -i -X POST \
  'https://api.checkrtrust.com/v1/criminal_checks?include%5B%5D=profile' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
      }
    ]
  }'

Responses

Accepted - Check created, results will be delivered via webhook. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.

Bodyapplication/json
idstring, (uuid)

The ID of the created check

statusstring

Status of the check (always 'pending' on creation)

Value:"pending"
created_atstring, (date-time)

Timestamp when the check was created

Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "created_at": "2019-08-24T14:15:22Z"
}

Callbacks

Criminal Check Completion Webhook
post