# Create driver risk signals check

Create a new driver risk signals 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.

Endpoint: POST /driver_risk_signals
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

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

## Query parameters:

  - `include[]` (array)
    Request optional response fields. Repeat the parameter for multiple values.

## Request body:

  - `application/json` (unknown)
    The request body for creating a new driver risk signals check.
Use either inline PII fields or `profile_id`—not both. See the POST `/driver_risk_signals` operation for details.

## Request fields (application/json):

  - `middle_name` (string)

  - `no_middle_name` (boolean)

  - `profile_id` (string, required)
    Identifier of an existing profile containing search criteria.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `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.

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

  - `ruleset_id` (string)
    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.
    Example: d16e88e6-aacc-4c42-9cd2-58a93dc9d8af

  - `ruleset_ids` (array)
    A list of ruleset identifiers to apply. When both `ruleset_id` and
`ruleset_ids` are provided, they are merged and de-duplicated before applying.

  - `limit` (integer)
    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.
    Example: 5

  - `score_threshold` (number)
    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.
    Example: 0

## Response 201:

  - `201` (unknown)
    Created.
When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.

## Response 201 fields (application/json):

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

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

  - `status` (string | null)
    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: "pending", "complete", "error", "null"

  - `check_type` (string)
    Enum: "driver_risk_signals"

  - `input_type` (string)
    Always `person` for this product -- driver_risk_signals has no address-based search path.
    Enum: "person", "address"

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

  - `results_info` (object)

  - `results_info.profiles_returned` (integer)
    Count of matched-profile entries in `results` that have at least one visible record --
not simply `results.length`, since `results` may also include matched identities with
an empty `records` array (see `results` below). Capped by the request's `limit` (or its
default/max), and reduced further by any ruleset applied on the request: a profile no
longer counts toward this total once all of its records are excluded by the ruleset,
even though the profile itself still appears in `results`.

  - `results_info.profiles_limit` (integer)
    The limit this search actually ran under -- the request's `limit`, echoed back.
    Example: 5

  - `results_info.profiles_truncated` (boolean)
    When `true`, this search matched more profiles than the requested `limit`, and
`results` holds the highest-scoring ones. A more specific search -- adding a date of
birth, a state, or an SSN -- is a way to bring the identity you are looking for into
range.

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

  - `results.match_confidence_level` (string)
    **Identity match confidence** for this matched profile, based on how strongly the identity
matched by our people data graph aligns with the PII you submitted for the check.
The values **high**, **medium**, and **low** are assigned based on Checkr's proprietary ML algorithm.
This is measured independently from each record's own `record_match_confidence_level` and from each
case's `identity_match_confidence_level` (see the `record`/`case` schema) -- a profile-level "high",
a record-level "high", and a case-level "high" are not derived from the same measurement and should
not be compared to each other.
    Enum: "high", "medium", "low"

  - `results.identity` (object)
    A conservative identity summary for the matched profile. This summary intentionally does not
include raw contact PII (emails, phone numbers) or document numbers, even when the underlying
identity provider carries them -- that exclusion applies only to this identity summary, not to
the matched profile's nested `records[]`, which may legitimately include a `doc_number` as
court-record data (see the `record` schema).

  - `results.identity.name_variations` (array)
    Name variations on file for this identity, most authoritative first, capped at 10 entries.

  - `results.identity.name_variations.full_name` (string)
    Example: Marcus G Williams

  - `results.identity.name_variations.first_name` (string)
    Example: Marcus

  - `results.identity.name_variations.middle_name` (string)
    Example: G

  - `results.identity.name_variations.last_name` (string)
    Example: Williams

  - `results.identity.dates_of_birth` (array)
    Dates of birth on file for this identity.

  - `results.identity.gender` (string)
    Enum: "male", "female", "non_binary", "other"

  - `results.identity.states` (array)
    US states associated with this identity's recent addresses on file. Limited to
approximately the last 5 years: where the identity provider reports when an address was
last observed, only addresses observed inside that window contribute; where it reports no
such date, the address history is sampled rather than used in full. This is therefore a
recent-residence indicator, not an exhaustive address or residence history, and it may be
absent entirely when no address falls inside the window.
    Example: ["FL","GA"]

  - `results.identity.photo_urls` (array)
    A set of URLs referencing photos of this person: photos on file for this identity, plus
any photos attached to this matched profile's returned `records[]` (for example, a
criminal record's mugshot). Only records visible in `records[]` contribute here -- a
record filtered out of the response never adds a photo to this list. Deduplicated, capped
at 20 entries. Same field name and shape as Instant Criminal Checks'
`record.person.photo_urls`.
    Example: ["https://example.com/pictures/marcus-selfie.jpg"]

  - `results.identity.deceased` (object)
    Whether the sources linked to this matched profile have reported the person as deceased, and
the date or dates of death they gave.

  - `results.identity.deceased.status` (string, required)
    The resolved answer across all sources linked to this profile.
    Enum: "deceased", "not_deceased", "conflict", "no_data"

  - `results.identity.deceased.dates_of_death` (array)
    Dates of death reported by the sources linked to this profile.
    Example: ["19630800"]

  - `results.records` (array)
    Criminal records associated with this matched profile. Same shape as the Instant Criminal Checks `record` schema.

  - `results.records.record_id` (string)
    An identifier for this record within the check result.
The same underlying record may share an ID across different checks. It is not a
permanent identifier: if the source data for a record changes, a later search may
return that record with a different ID.
    Example: record-7480fc7edac1a09867849999f2a2f6eec3cc37150f4ba65cbd1f46a4a1a5c15e

  - `results.records.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.records.collection_date` (string)
    A date in the form YYYYMMDD.
    Example: 19950401

  - `results.records.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.records.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.records.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.records.person.first_name` (string)
    Example: John

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

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

  - `results.records.person.suffix` (string)

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

  - `results.records.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.records.person.gender` (string)
    The gender, if any, as recorded by the source.  No specific format.
    Example: M

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

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

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

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

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

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

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

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

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

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

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

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

  - `results.records.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.records.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.records.person.addresses.city` (string)
    City or municipality when reported by the source.
    Example: Frankfort

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

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

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

  - `results.records.source` (object)

  - `results.records.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.records.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.records.source.name` (string)
    A human-understandable (English) name of the source.
    Example: KY Franklin County Inmates

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

  - `results.records.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.records.cases` (array)
    Only fields that have a value are returned.  Most cases will have only a subset of these fields.

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

  - `results.records.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.records.cases.type` (string)
    The case type as reported by the court.  Not present for records which are not from a court.  Format varies.

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

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

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

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

  - `results.records.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.records.cases.charges` (array)
    Only fields that have a value are returned.  Most charges will have only a subset of these fields.

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

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

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

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

  - `results.records.cases.charges.degree` (string)
    Court-reported offense degree, as written on the record.
    Example: MISDEMEANOR - CLASS B

  - `results.records.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.records.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.records.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.records.cases.charges.city` (string)
    The name of the city where the person was charged
    Example: Indian Hills

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

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

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

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

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

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

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

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

## 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 403:

  - `403` (unknown)
    Error response

## Response 403 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. Present only when the
product configuration has usage limits.
    Example: 100

  - `X-RateLimit-Remaining` (string)
    Number of calls remaining in the current limit period. Present only when the product
configuration has usage limits.
    Example: 0

  - `X-RateLimit-Expires` (string | null)
    ISO 8601 timestamp after which product access expires. Present only when the product
configuration has an access expiry (`access_expires_at`).

## 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