Create a new regulated instant criminal profile check. results is an array of matched identities (profiles), each with its own nested criminal records, sorted best match first -- so you can review which identity matched before drilling into its records. A FCRA permissible_purpose and a date of birth are required. Every record is evaluated against applicable legal rules, and records your account is not permitted to see are omitted from results; see the response schema for how matching, limits, and filtering shape results.
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 regulated instant criminal profile check.
Create a regulated instant criminal profile 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.
The lowest match_confidence_level a matched profile must have to be included in results, for this request only. Profiles below this level are excluded from the response.
high(the default): only profiles whose identity details are close to identical to the PII you submitted.medium:highandmediumprofiles.low: every matched profile our identity provider returned, with no filtering.
When omitted, your account's configured minimum applies, which is high unless Checkr has set it otherwise for your account.
The permissible purpose for requesting this criminal record check, as required by the Fair Credit Reporting Act (FCRA). This must be provided for all regulated instant criminal checks to ensure compliance with federal regulations.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/regulated/instant_criminal_profiles
curl -i -X POST \
'https://api.checkrtrust.com/v1/regulated/instant_criminal_profiles?include%5B%5D=profile' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "Marcus",
"last_name": "Williams",
"dob": "19880315",
"permissible_purpose": "Insurance Underwriting",
"filter_context": {
"candidate_jurisdiction": {
"state": "CA"
}
}
}'Created.
Maximum number of API calls allowed for this product configuration. Present only when the product configuration has usage limits.
Number of calls remaining in the current limit period. Present only when the product configuration has usage limits.
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 a profile-family criminal check (driver_risk_signals, instant_criminal_profiles, regulated/instant_criminal_profiles). 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 |
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, legally annotated records. Empty array when no identity matched at all, or when every matched identity fell below the effective minimum match confidence (high by default, or this request's min_match_confidence_level) -- a below-minimum match is excluded entirely, not included with records: [].
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 identifier for a matched identity is exposed; the top-level profile_id is the profile you submitted), so position in this array is the only way to refer to a specific match (e.g. "the 1st match").
Records, cases, and charges excluded by legal rules are omitted. If your account is configured as a consumer reporting agency (CRA), items marked investigate are included for you to review. A matched identity whose records were all removed -- by legal filtering, by a ruleset applied on the request, or by de-duplication -- still appears, with records as an empty array, and does not count toward results_info.profiles_returned.
{ "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "created_at": "2020-01-01T00:00:00Z", "completed_at": "2020-01-01T00:00:00Z", "status": "complete", "check_type": "instant_criminal_profile_regulated", "input_type": "person", "reference_id": "ref-123", "results_info": { "profiles_returned": 0, "profiles_limit": 5, "profiles_truncated": true }, "results": [ { … } ], "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890" }