Create a new county criminal check for a county jurisdiction, or a state-level criminal check when county_fips_code is the literal statewide (case-insensitively).
This endpoint supports three mutually exclusive search modes:
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. reference_id may be sent alongside profile_id. Empty addresses: [] counts as a supplied address parameter and cannot be paired with profile_id.
PII search — provide subject identifying information directly:
- first_name (required)
- last_name (required)
- dob (required)
- state (required)
- county_fips_code (required) — 5-digit county FIPS, or
statewidefor a state-level search
Profile search — reference an existing profile:
- profile_id (required)
- state (required)
- county_fips_code (required) — 5-digit county FIPS, or
statewidefor a state-level search
Case number search — search by a specific court case number (NC and MN only):
- case_number (required) — letters, numbers, spaces, and hyphens only
- state (required) —
NCorMN - county_fips_code (required) — 5-digit county FIPS
These three modes are mutually exclusive — do not combine case_number with first_name/last_name, dob, profile_id, or lookback_period_in_years in the same request.
The request body for creating a county check
Request to create a county check 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.
First name of the person. Required (with last_name) when not sending full_name or using profile_id.
Last name of the person. Required (with first_name) when not sending full_name or using profile_id.
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. If you already know the first and last names, we suggest sending them.
Date of birth in the form YYYYMMDD. Must be a valid date and cannot be in the future. Required when not using profile_id.
The two-letter US state code for the search jurisdiction (county or statewide).
Use a 5-digit county FIPS code for a county-level criminal search. Use the literal statewide for a state-level criminal search covering the jurisdiction identified by state (the API accepts statewide case-insensitively and normalizes it to lowercase in stored search criteria).
Optional number of years to look back for criminal records. If not provided, the default lookback period configured for the account will be used.
Optional override for this request indicating whether to include records with a null date of birth. If omitted, your account's default setting is used (or 'true' if not configured).
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
Primary address for the candidate. Used during result processing for identity matching and ROSIE scoring. Prefer addresses for new integrations; when both are provided, address is treated as the primary entry.
On inline create (without profile_id), optional address or addresses[] are saved to the new profile.
Optional addresses associated with the candidate. Used during result processing for identity matching and ROSIE scoring. Index 0 is the primary address.
On inline create, addresses are saved to the new profile.
- Checkr Trust APIhttps://api.checkrtrust.com/v1/county_checks
curl -i -X POST \
'https://api.checkrtrust.com/v1/county_checks?include%5B%5D=profile' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "Jane",
"middle_name": "Mary",
"last_name": "Smith",
"dob": "19900115",
"state": "CA",
"county_fips_code": "06075",
"lookback_period_in_years": 7
}'Created
A universally unique identifier (UUID) in standard format.
An ISO 8601 formatted date-time string.
An ISO 8601 formatted date-time string.
The type of county check.
The current status of the county check.
pending— the check has been submitted and is awaiting results.complete— results are available. Acounty_criminal.completedwebhook is delivered.cancelled— the search was cancelled, either at your request or because it could not be completed. When a search cannot be completed, acounty_criminal.not_availablewebhook is delivered.
A machine-readable reason for a check's error status. Only present when the check has errored.
provider_error— the third-party data provider returned an unrecoverable error.timeout— the check did not complete within the allowed time window.cancelled— the check was cancelled, either at your request or because it could not be completed.need_more_info— additional identity information (e.g. email or SSN) is required to view results.
A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
The search criteria used for the county check. Field presence depends on how the check was submitted:
- PII or profile search — includes
first_name,last_name, and usuallydate_of_birth(from the request or linked profile).case_numberis omitted. - Case number search — includes
case_number. Name and date-of-birth fields are omitted.
The results of the county check. Empty array if no records found or if the check is still pending.
An unstructured array of human-readable notes about this particular check. May contain notes about how input was parsed or other information about results. Not intended to be parsed by computer, as these notes are not guaranteed to be in any given format.
[ "used no ruleset" ]
Identifier of an existing profile containing search criteria.
{ "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "created_at": "2020-01-01T00:00:00Z", "completed_at": "2020-01-01T00:00:00Z", "check_type": "county_criminal", "status": "pending", "error_reason": "cancelled", "reference_id": "ref-123", "search_criteria": { "first_name": "Jane", "middle_name": "Mary", "last_name": "Smith", "date_of_birth": "2020-01-01", "state": "CA", "county_fips_code": "06075", "lookback_period_in_years": 7, "case_number": "1992CRS000215" }, "results": [ { … } ], "run_notes": [ "used no ruleset" ], "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890", "profile": { "id": "2b8313e8-4efd-45a1-b578-952b8313e890", "full_name": "string", "first_name": "string", "middle_name": "string", "no_middle_name": false, "last_name": "string", "dob": "19950401", "phone": "+14155552671", "country_code": "string", "email": "john.doe@example.com", "ssn": "123-45-6789", "address": { … }, "addresses": [ … ], "custom_id": "my-custom-id-123", "driver_license_state": "CA", "driver_license_number": "D1234567" } }