Create a new regulated criminal report with legal annotation.
This endpoint creates an asynchronous criminal report that applies legal rules based on the provided jurisdiction context. Results include legal annotation checks at the record, case, and charge levels indicating whether items should be included, investigated, or removed based on applicable regulations.
A permissible purpose must be provided to comply with Fair Credit Reporting Act (FCRA) requirements.
Profile vs inline PII: Submit either a profile_id or inline PII/address fields—not both. Combining profile_id with name fields, 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 addresses: [] counts as a supplied address parameter and cannot be paired with profile_id.
Important Notes:
- Results are NOT returned in the HTTP response (returns 202 Accepted)
- Full results are delivered asynchronously via webhook once processing is complete
The request body for creating a new regulated criminal report. 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 /regulated/criminal_reports operation for details.
Request to create a regulated criminal report using personally identifiable information (PII).
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.
The type of check performed for this report.
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. With no_middle_name: true, any parsed middle token is folded into the last name instead of being stored as a middle name.
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. 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" } ]
Context information used to determine which legal rules apply when filtering report results. Jurisdictions help identify applicable state and local regulations that may affect which records can be reported.
{ "candidate_jurisdiction": { "state": "CA" }, "decider_jurisdiction": { "state": "NY" } }
The permissible purpose for requesting this criminal record report, as required by the Fair Credit Reporting Act (FCRA). This must be provided for all regulated criminal reports to ensure compliance with federal regulations.
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.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/regulated/criminal_reports
curl -i -X POST \
https://api.checkrtrust.com/v1/regulated/criminal_reports \
-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"
}
],
"filter_context": {
"candidate_jurisdiction": {
"state": "CA"
},
"decider_jurisdiction": {
"state": "NY"
}
},
"permissible_purpose": "Employment"
}'Accepted - Report 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.
{ "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "status": "pending" }