Create a new criminal check. The check is created and processed asynchronously; results are not returned in the create response.
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 become available via GET once the check completes
- When a webhook destination_url is configured on the product configuration, results are also delivered asynchronously via webhook
The request body for creating a new criminal check. Results become available via GET once the check completes. When a webhook is configured, they are also delivered asynchronously.
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.
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.
First name (given name). Do not include prefixes such as "Ms." or "Dr."
Last name (surname). Do not include suffixes such as "Jr." or "2nd".
Either send the full name, or first, middle (optional), and last names, but not both. If you send a full name, we will attempt to parse it into first name, middle name(s) and last name, and then use those for the check. With no_middle_name: true, any parsed middle token is folded into the last name instead of being stored as a middle name. If you already know the first and last names, we suggest sending them. The parser will attempt to remove prefixes and suffixes, and handles several different formats of name, but we cannot guarantee it will parse the name in the manner you expect.
The type of input being provided for the search. Can be either a person's information or an address.
Date of birth in the form YYYYMMDD. Must be a valid date and cannot be in the future. If invalid, the API returns a 400 with a validation_error pointing to /dob.
Social Security Number used for additional identity verification and record matching
A phone number in the form +[country code][number including area code]. (E.164 format). Please note that U.S. phone numbers have a country code of "1" so all U.S. phone numbers ought to start with "+1". A U.S. number supplied in national format (for example "(415) 555-0123") is normalized to E.164 on write. If the value cannot be parsed as a valid phone number, the API returns a 400 with a validation_error.
An array of addresses to search for criminal records. When provided, records will be matched against any of the addresses in the array. Index 0 is the primary address.
On inline create, addresses are saved to the new profile.
[ { "street": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip_code": "90001" } ]
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.
A list of ruleset identifiers to apply. When both ruleset_id and ruleset_ids are provided, they are merged and de-duplicated before applying.
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
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.
Specifies the field to sort the results by. Currently only supported for 'photo_urls'.
Set to true to declare that the subject does not have a middle name.
Mutually exclusive with a non-empty middle_name: the API rejects requests that supply both a present middle_name and no_middle_name: true. An empty or null middle_name with no_middle_name: true is allowed. A non-empty middle_name may be supplied with no_middle_name: false.
Allowed with full_name: full_name and no_middle_name may be sent together. That is not the same as supplying middle_name — when the flag is true, parsing stores only a first name and surname, and any token the parser would have treated as a middle name is folded into the last name (for example full_name: "John Quincy Doe" becomes first name John and last name Quincy Doe, with middle_name empty).
Setting this to true clears a middle name already stored on a referenced profile. Supplying a non-empty middle_name without this field sets no_middle_name to false. When true, products that perform criminal-record identity matching exclude records with a middle name, narrowing matches to subjects with no middle name on record. When supplied with profile_id, the value is persisted to the referenced profile (same account-scoped profile the check is created against). Leave as false (or omit) if unsure.
Multi-source deduplication runs by default for instant criminal, targeted instant criminal, sex offender registry, and criminal_check (via POST /v1/criminal_checks). It may merge or suppress duplicate rows across data providers.
falseor omit: apply deduplication for this check.true: skip multi-source deduplication; results may include duplicate source rows in storage and in API responses (and webhooks forcriminal_check).
Create-time only: send on create; not a query parameter on GET.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/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"
}
]
}'Accepted - Check created. Results become available via GET once complete, and via webhook when configured. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "pending", "created_at": "2019-08-24T14:15:22Z" }