Profile Criminal Checks provide a people-data-graph-native, profile-centric alternative to Instant Criminal Checks. Instead of a flat records array, results is an array of matched identities (profiles) -- each with a conservative identity summary and its own nested criminal records -- so you can review which identity matched before drilling into its records.
Beta: Profile Criminal Checks are in beta and not yet generally available.
Create a new profile criminal check. Unlike Instant Criminal Checks, results is an array of matched identities (profiles) with their own nested records, rather than a flat records array -- so a customer can first review which identity matched before drilling into its records.
Beta: Profile Criminal Checks are in beta and not yet generally available.
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"). Empty address: {} or addresses: [] count as supplied address parameters and cannot be paired with profile_id.
The request body for creating a new profile criminal check.
Use either inline PII fields or profile_id—not both. See the POST /profile_criminal_checks operation for details.
Create a profile criminal check using inline 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.
first name (given name). Do not include prefixes, like "Ms." or "Dr."
Either send the full name, or first and last names, but not both. If you send a full name, Checkr 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. Not required by this schema, but in practice a search without a date of birth cannot be satisfied by our identity provider today and returns 400 provider_error.
A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.
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.
Driver license number. Format depends on the issuing state. Send this together with driver_license_state or not at all: the two are combined into a single JURISDICTION:LICENSE value before being matched, so a number sent without a state is matched as a different value and will silently fail to find the driver it identifies.
State that issued the driver license. Required whenever driver_license_number is sent (see that field). Unlike driver license status checks, this is not restricted to states with DMV data-access agreements -- any US state or protectorate is accepted.
An identifier of your choice, if you wish to use one. Limited to 64 alphanumeric characters, underscores, and hyphens.
On inline create (without profile_id), optional address or addresses[] are saved to the new profile.
On inline create (without profile_id), optional address or addresses[] are saved to the new profile.
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
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.
Maximum number of matched profiles to return in results, ranked by identity match strength (best first). Send 1 when you only want the single best identity match; raise it to review several candidate identities. This limits profiles only -- each returned profile still carries all of its records.
Overrides, for this request only, the minimum identity-match score a matched profile must meet to be included in results. Profiles scoring below this value are excluded from the response.
When omitted, the account's configured minimum score is used. Send 0 to disable score-based filtering entirely and review every matched profile our identity provider returned, regardless of score.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/profile_criminal_checks
curl -i -X POST \
'https://api.checkrtrust.com/v1/profile_criminal_checks?include%5B%5D=profile' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "Marcus",
"last_name": "Williams",
"dob": "19880315"
}'Created. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.
A universally unique identifier (UUID) in standard format.
An ISO 8601 formatted date-time string.
An ISO 8601 formatted date-time string.
The current status of the profile criminal check. This is the only field that separates a search that failed from one that ran and had nothing to report -- completed_at, results_info and results look identical in both cases.
null on checks created before this field was introduced. A null status is not an error: those checks did run, so read completed_at and results_info to tell whether one finished.
| Enum Value | Description |
|---|---|
| pending | The search has been submitted and is awaiting results. Rare for this product, which completes synchronously on create. |
| complete | The search ran and |
| error | The search could not be completed, so |
Always person for this product -- profile_criminal_check has no address-based search path.
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
Array of matched identities (profiles), each with its own nested records. Empty array when no identity matched at all, or when every matched identity scored below the effective minimum match score (the account's configured minimum, or this request's score_threshold override) -- a below-threshold match is excluded entirely, not included with records: []. A matched profile that clears the score threshold but has all of its records excluded (by a ruleset applied on the request, or by de-duplication) still appears here, with records as an empty array -- the identity match itself remains reportable even when nothing survived filtering. Sorted by match_confidence_level's underlying score, descending -- the best match is always first. Capped at the request's limit (default 10, max 20). This ordering is a stable contract you can rely on: matched profiles are not otherwise individually identifiable (no profile_id is exposed), so position in this array is the only way to refer to a specific match (e.g. "the 1st match").
{ "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890" }