# Cancel county check

Cancel an existing county check that is in a pending state.

A reason must be provided for the cancellation. Only checks that are
currently in 'pending' status can be cancelled.

Endpoint: POST /county_checks/{county_check_id}/cancel
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

  - `get-bearer-token-using-oauth2` (unknown)
    oauth2

## Path parameters:

  - `county_check_id` (string, required)
    The uuid identifying the county check

## Query parameters:

  - `include[]` (array)
    Embed the profile in the response in place of `profile_id`.

## Request body:

  - `application/json` (unknown)
    The request body for cancelling a county check

## Request fields (application/json):

  - `reason` (string, required)
    The reason for cancelling the county check.
    Example: Candidate withdrew application

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `id` (string, required)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `created_at` (string, required)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `completed_at` (any)
    The timestamp when the check was completed. Null if still pending.

  - `check_type` (string, required)
    The type of county check.
    Enum: "county_criminal"

  - `status` (string, required)
    The current status of the county check.
- `pending` — the check has been submitted and is awaiting results.
- `complete` — results are available. A `county_criminal.completed` webhook is delivered.
- `cancelled` — the search was cancelled, either at your request or because it could not
be completed. When a search cannot be completed, a `county_criminal.not_available` webhook
is delivered.
    Enum: "pending", "complete", "cancelled"

  - `error_reason` (string)
    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.
    Enum: "provider_error", "timeout", "cancelled", "need_more_info"

  - `reference_id` (string)
    A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.
    Example: ref-123

  - `search_criteria` (object, required)
    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 usually `date_of_birth`
(from the request or linked profile). `case_number` is omitted.
- **Case number search** — includes `case_number`. Name and date-of-birth fields are omitted.

  - `search_criteria.first_name` (string)
    First name of the person. Present for PII and profile searches; omitted for case-number searches.
    Example: Jane

  - `search_criteria.middle_name` (string)
    Middle name of the person. Present for PII and profile searches when supplied; omitted for case-number searches.
    Example: Mary

  - `search_criteria.last_name` (string)
    Last name of the person. Present for PII and profile searches; omitted for case-number searches.
    Example: Smith

  - `search_criteria.date_of_birth` (string)
    Date of birth in the form YYYY-MM-DD. Present for PII and profile searches; omitted for case-number searches.
    Example: 2020-01-01

  - `search_criteria.state` (string)
    A two-letter US state code.
    Example: CA

  - `search_criteria.county_fips_code` (any)
    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).

  - `search_criteria.lookback_period_in_years` (integer)
    The number of years to look back for criminal records. Present for PII and profile searches;
omitted for case-number searches.
    Example: 7

  - `search_criteria.case_number` (string)
    The court case number used for the search. Present only for case-number searches;
omitted for PII and profile searches.
    Example: 1992CRS000215

  - `results` (array, required)
    The results of the county check.
Empty array if no records found or if the check is still pending.

  - `results.record_id` (string)
    A stable identifier for this record, derived from the record content.
Format: `record-{sha256_hash}`.
This ID is globally unique across all checks and can be referenced
in adverse action requests to identify disqualifying records.
    Example: record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

  - `results.category` (string)
    A categorization of the type of record returned.
Maps closely to the source category, except PA sources can contain either Patriot or Registry records.
    Enum: "arrest", "Criminal/traffic", "Warrant", "Sex Offender", "Patriot", "Registry"

  - `results.collection_date` (string)
    A date in the form YYYYMMDD.
    Example: 19950401

  - `results.collection_date_notice` (string)
    Disclaimer accompanying `collection_date` on Virginia records only: VA records may
have been sealed by the court since the date the record was collected. Only present
together with `collection_date`; when the date is omitted (no usable date), the
notice is omitted as well.
    Example: This information may include records that have been sealed since the collection date shown above.

  - `results.record_match_confidence_level` (string)
    **Record match confidence** for this record: how strongly this record aligns with the identity it was matched
to. Returned only for records sourced from Checkr's people data graph.
The values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.
**Not comparable to other confidence fields.** This is measured independently from the case-level
`identity_match_confidence_level` (below) and, on Driver Risk Signals / Instant Criminal Profile, from the
profile-level `match_confidence_level`. The three answer different questions and are calibrated separately,
so a **high** on one does not mean the same thing as a **high** on another.
**Absence:** Omitted when the record's source does not supply a match confidence.
    Enum: "high", "medium", "low"

  - `results.person` (object)
    Person attributes as reported on this record. Only fields that have a value are returned;
most records include only a subset of these fields.

  - `results.person.first_name` (string)
    Example: John

  - `results.person.middle_name` (string)
    middle initial or name or names
    Example: W

  - `results.person.last_name` (string)
    Example: Smith

  - `results.person.suffix` (string)

  - `results.person.full_name` (string)
    Example: Smith, John W.

  - `results.person.dob` (string)
    A date or partial date in the form YYYYMMDD.
Since some dates are partial, they may be represented as YYYY0000 or 0000MMDD or YYYYMM00.
    Example: 19950401

  - `results.person.doc_number` (string)
    Dept. of Corrections number.
A number or identifier given by a state Dept. of Corrections to identify a person who went to prison.

  - `results.person.gender` (string)
    The gender, if any, as recorded by the source.  No specific format.
    Example: M

  - `results.person.height` (string)
    The height, if any, as recorded by the source.  No specific format.
    Example: 601

  - `results.person.weight` (string)
    The weight, if any, as recorded by the source.  No specific format.
    Example: 180

  - `results.person.hair_color` (string)
    The hair color, if any, as recorded by the source.  No specific format.
    Example: BRN

  - `results.person.eye_color` (string)
    The eye color if any, as recorded by the source.  No specific format.
    Example: HAZ

  - `results.person.skin_color` (string)
    The skin color, if any, as recorded by the source.  No specific format.
    Example: wht

  - `results.person.race` (string)
    The race as defined by the source.  No specific format.
    Example: W

  - `results.person.ethnicity` (string)
    The ethnicity, if any, as recorded by the source.  No specific format.
    Example: Hispanic-American

  - `results.person.physical_build` (string)
    The physical build, if any, as recorded by the source.  No specific format.
    Example: BROAD

  - `results.person.physical_marks` (string)
    Scars, marks, and tattoos as defined by the source.  No specific format.
    Example: blue cross on outside left ankle

  - `results.person.photo_urls` (array)
    A set of URLs referencing pictures of this person, as recorded by the source.

  - `results.person.name_aliases` (array)
    Other names that this person may have gone by.

  - `results.person.dob_aliases` (array)
    Other dates of birth that this person may have used.

  - `results.person.addresses` (array)
    Addresses associated with this person on this record, as reported by the data source.
Omitted when the source provides no address information. Each entry may be partial.
    Example: [{"street":"123 Main St","city":"Frankfort","state":"KY","zip_code":"40601"},{"street":"OFFENDER REPORTS MOVED OUT OF UTAH"}]

  - `results.person.addresses.street` (string)
    Street or location line as reported by the source. May be a free-form string rather than a
normalized postal address (for example, a registry status message).
    Example: 123 Main St

  - `results.person.addresses.city` (string)
    City or municipality when reported by the source.
    Example: Frankfort

  - `results.person.addresses.state` (string)
    State as reported by the source, if any.
    Example: KY

  - `results.person.addresses.zip_code` (string)
    ZIP code as reported by the source, if any.
    Example: 40601

  - `results.person.addresses.country` (string)
    Country as reported by the source, if any.
    Example: US

  - `results.source` (object)

  - `results.source.id` (string)
    An identifier for the source.  E.g. "cookil" or "NJ_Supreme_Ct_view".  Can be used to programmatically exclude a source.
    Example: ARSTfranklinKY

  - `results.source.category` (string)
    A categorization of the type of source where the data was retrieved.
Some of the categories may not imply wrongdoing, and are excluded by default.
    Enum: "arrest", "court", "criminal registry", "DOC", "warrant", "sex offender registry", "domestic watchlist", "foreign watchlist", "healthcare registry", "healthcare sanctions", "financial registry", "financial sanctions", "other registry", "other sanctions", "PEP registry"

  - `results.source.name` (string)
    A human-understandable (English) name of the source.
    Example: KY Franklin County Inmates

  - `results.source.county` (string)
    The name of the county (if any) where the record came from.
    Example: Franklin

  - `results.source.county_fips_code` (string)
    The 5-digit FIPS code of the county where the record came from.
Present for county checks; omitted for sources without an associated county.
    Example: 17031

  - `results.cases` (array)
    Only fields that have a value are returned.  Most cases will have only a subset of these fields.

  - `results.cases.case_id` (string)
    A stable identifier for this case, derived from the case content.
Format: `case-{sha256_hash}`.
    Example: case-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

  - `results.cases.case_number` (string)
    The case number assigned by a court.  Not present for records which are not from a court.  Format varies.
    Example: 2025-99999

  - `results.cases.type` (string)
    The case type as reported by the court.  Not present for records which are not from a court.  Format varies.

  - `results.cases.status` (string)
    The case status as reported by the court.  Sparsely available.  Format varies.

  - `results.cases.arresting_agency` (string)
    The name of the arresting agency.
    Example: Franklin County Sheriff

  - `results.cases.court_name` (string)
    The name of the charging court.
    Example: Franklin County Circuit Court

  - `results.cases.court_county` (string)
    The county of the charging court.
    Example: Franklin

  - `results.cases.identity_match_confidence_level` (string)
    **Identity match confidence** for this case. When present, it indicates how strongly this criminal case aligns
with the PII you submitted for the check.
Distinct from the record-level `record_match_confidence_level`: this field is about a single **case** versus the
PII you submitted, while that one is about a whole **record** versus the identity it was matched to. They are
measured separately and should not be compared to each other.
The values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.
**Other values:** **unknown** — identity matching was enabled for the check but a confidence label could not be determined for this case. **insufficient_information** — identity matching was skipped (for example, insufficient identifiers); check `run_notes` for context.
**Absence:** Omitted when identity matching was not enabled for the check. Reach out to support@checkrtrust.com if you are interested in enabling this feature
    Enum: "high", "medium", "low", "unknown", "insufficient_information"

  - `results.cases.charges` (array)
    Only fields that have a value are returned.  Most charges will have only a subset of these fields.

  - `results.cases.charges.charge_id` (string)
    A stable identifier for this charge, derived from the charge content.
Format: `charge-{sha256_hash}`.
    Example: charge-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

  - `results.cases.charges.description` (string)
    The description of the offense, as reported on the record.  Format varies.
    Example: SHOPLIFTING

  - `results.cases.charges.legal_code` (string)
    Legal code (statute) as reported by the court or arresting agency.
    Example: 433.234

  - `results.cases.charges.type` (string)
    the type (level, severity) of a charge
    Enum: "felony", "misdemeanor", "petty_offense", "unknown"

  - `results.cases.charges.category` (string)
    the highest level of categorization of a charge
    Enum: "Criminal Intent", "Drugs & Alcohol", "Fraud & Deception", "Homicide", "Security", "Sexual", "Statutory", "Theft & Property", "Vehicles & Traffic", "Violence", "unclassified"

  - `results.cases.charges.subcategory` (string)
    the second level of categorization of a charge
    Enum: "Accessory", "Conspiracy", "Court Orders", "Criminal Tools", "Obstruction", "Organized Crime", "Alcohol & Tobacco", "Driving under the Influence (DUI)", "Drugs-Marijuana Possession/Use", "Drugs-Possession/Use", "Drugs-Sale & Manufacture", "Bribery & Corruption", "Business & Tax", "Cyber Crimes", "Embezzlement", "Forgery", "Fraud", "Identity Theft & Impersonation", "Worthless Check", "Attempted Homicide", "Intentional Homicide", "Unintentional Killing", "Immigration", "Terrorism", "Treason", "Lewd Behavior", "Prostitution", "Sexual Abuse", "Animal Ordinances", "Custody & Support", "Fish & Game", "Gambling", "Miscellaneous Citations & Violations", "Public Nuisance", "Safety & Zoning", "Arson", "Burglary", "Petty Theft", "Possession of Stolen Property", "Robbery", "Theft", "Trespassing", "Vandalism & Mischief", "License & Registration", "Parking", "Speeding", "Unsafe Operation", "Vehicle Equipment", "Abduction & Restraint", "Animal Cruelty", "Assault & Battery", "Child & Elder Abuse", "Disorderly Behavior", "Harassment & Threats", "Weapons & Endangerment", "unclassified"

  - `results.cases.charges.subsubcategory` (string)
    The lowest (most detailed) level of categorization of a charge.
There are over 250 of these.
They are one of the categorizations on which rulesets operate.
    Example: Retail Theft

  - `results.cases.charges.city` (string)
    The name of the city where the person was charged
    Example: Indian Hills

  - `results.cases.charges.county` (string)
    The name of the county where the person was charged
    Example: Jefferson

  - `results.cases.charges.state` (string)
    The state where the person was charged
    Example: KY

  - `results.cases.charges.sentences` (array)

  - `results.cases.charges.sentences.release_type` (string)
    Type of release, if reported.

  - `results.cases.charges.sentences.details` (string)
    Description of the sentence, if any
    Example: fine, 1D

  - `results.cases.charges.dispositions` (array)

  - `results.cases.charges.dispositions.disposition` (string)
    A description of the disposition, as provided by the court, if any.
    Example: GLT

  - `results.cases.charges.dispositions.disposition_type` (string)
    the type of disposition
    Enum: "Conviction", "Dismissed", "Invalid", "Merged", "Pending", "Transferred", "Warrant", "Unclassified"

  - `run_notes` (array)
    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.

  - `profile_id` (any)
    Profile UUID when the check is associated with a profile. `null` for case-number searches.
Omitted when `include[]=profile` is used — use the nested `profile` object instead.

  - `profile` (object)
    A profile containing personal information used for checks and verifications.

  - `profile.full_name` (string)
    The full name of the person. Must not be combined with first_name, middle_name, or last_name.
May be combined with `no_middle_name` on create/update; when that flag is `true`, parsing
stores only a first name and surname (any middle token is folded into the last name).

  - `profile.first_name` (string)
    The first name of the person.

  - `profile.middle_name` (string)
    The middle name of the person. Can be null if not provided.

  - `profile.no_middle_name` (boolean)
    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.

  - `profile.last_name` (string)
    The last name of the person.

  - `profile.dob` (string)
    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`.
    Example: 19950401

  - `profile.phone` (string)
    A phone number in the form +[country code][number including area code].
([E.164 format](https://en.wikipedia.org/wiki/E.164)).
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`.
    Example: +14155552671

  - `profile.country_code` (string)
    The phone country calling code supplied for a reverse phone verification (for example, "1" or "54").

  - `profile.email` (string)
    An email address.
    Example: john.doe@example.com

  - `profile.ssn` (any)
    US Social Security Number.
**Masked by default** — API responses return `XXX-XX-{last4}`. Full SSN is
available via `?unmask_ssn=true` on endpoints that support it (driver checks and
identity verifications), subject to your account's product configuration. Contact
your account representative to enable SSN unmasking.
**Always `null` on list/index endpoints** (e.g. `GET /profiles`, `GET /checks`), regardless
of masking or unmasking settings. Fetch the individual resource (e.g. `GET /profiles/{id}`)
to see the masked or unmasked value for a specific record.
May also be null on a single-resource response when no SSN was provided.
    Example: XXX-XX-6789

  - `profile.address` (object)
    A US postal address supplied in a **request** (for example on check create or profile create/update).
When this object is present, `street`, `city`, `state`, and `zip_code` are required.

  - `profile.address.street` (string, required)
    Street address, including house/building number and street name.
Apartment or unit numbers may be included; they are stored but are not used for criminal-record address matching.
    Example: 123 Main St

  - `profile.address.city` (string, required)
    The name of the city or municipality.
    Example: Frankfort

  - `profile.address.zip_code` (string, required)
    US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).
    Example: 94105

  - `profile.address.country` (string)
    A two-letter country code in ISO 3166-1 alpha-2 format.
    Example: US

  - `profile.addresses` (array)
    **Request only.** Array of addresses supplied by the caller. Index 0 is the primary address.
When the property is provided, at least one address entry is required.
Maximum 30 addresses.
For check requests, records may be matched against any address in the array.
The singular `address` field remains supported for backwards compatibility and maps to the primary address.

  - `profile.custom_id` (string)
    An identifier of your choice, if you wish to use one. Limited to 64 alphanumeric characters, underscores, and hyphens.
    Example: my-custom-id-123

  - `profile.driver_license_number` (string)
    The driver license number. Format dependent on State.
    Example: D1234567

## Response 400:

  - `400` (unknown)
    Error response

## Response 400 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 401:

  - `401` (unknown)
    Error response

## Response 401 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 404:

  - `404` (unknown)
    Error response

## Response 404 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 429:

  - `429` (unknown)
    Too Many Requests - the product configuration has reached its usage limit or product access has expired.
When usage limits are configured, the response includes X-RateLimit-* headers (see below).

## Response 429 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 429 headers (application/json):

  - `X-RateLimit-Limit` (string)
    Maximum number of API calls allowed for this product configuration.
    Example: 100

  - `X-RateLimit-Remaining` (string)
    Number of calls remaining in the current limit period.
    Example: 0

  - `X-RateLimit-Expires` (string | null)
    ISO 8601 timestamp after which product access expires (present only when access_expires_at is set).

## Response 500:

  - `500` (unknown)
    Error response

## Response 500 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 502:

  - `502` (unknown)
    Error response

## Response 502 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name