# Create regulated check

Create a new regulated criminal background check with legal annotation.

This endpoint performs an instant criminal check and applies legal rules based on
the provided jurisdiction context. Results include legal annotation checks at the
record, case, and charge levels indicating whether items should be included,
investigated, or removed based on applicable regulations.

A permissible purpose must be provided to comply with FCRA requirements.

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

## Query parameters:

  - `include` (array)
    Include related resources in the response

## Response 201 fields (application/json):

  - `id` (string)
    A universally unique identifier (UUID) in standard format.

  - `created_at` (string)
    An ISO 8601 formatted date-time string.

  - `completed_at` (string)
    An ISO 8601 formatted date-time string.

  - `results` (array)
    When there are no results found, this will be an empty array.

  - `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.person` (object)

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

  - `results.person.inferred_dob` (string)
    Some records which do not already have a full DOB may have an inferred full DOB that was found by other means.
For example a record may have no dob, or only a partial dob, but we were able to inferred a full dob using other similar records.

  - `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.
    Example: ["Johnny Smith"]

  - `results.person.dob_aliases` (array)
    Other dates of birth that this person may have used.
    Example: ["19940321"]

  - `results.person.addresses` (array)
    Addresses that are recorded for this person on this record.

  - `results.person.addresses.street` (string, required)
    The street address, including house/building number and street name. Apartment/unit numbers may be included but are not used for matching.
    Example: "123 Main St"

  - `results.person.addresses.city` (string, required)
    The name of the city or municipality.
    Example: "Frankfort"

  - `results.person.addresses.state` (string, required)
    The two-letter US state code where the address is located.

  - `results.person.addresses.zip_code` (string, required)
    The US postal ZIP code for the address.

  - `results.person.addresses.country` (string)
    The two-letter country code, typically "US" for United States addresses.

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

  - `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.file_date` (string)
    The date the case was filed as reported by the court.  Not present for records which are not from a court.
    Example: "19950401"

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

  - `results.cases.arrest_date` (string)
    The date the person was arrested.
    Example: "19950401"

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

  - `results.cases.checks` (array)
    Legal annotation check results for this case.

  - `results.cases.checks.action_type` (string)
    The action type determined by the legal rule evaluation:
- note: Informational annotation added to the item
- investigate: The item may require further review before inclusion
- remove: The item should not be reported based on legal restrictions
- modified: The item was modified (e.g., certain attributes were removed)
    Enum: "note", "investigate", "remove", "modified"

  - `results.cases.checks.rule_id` (string)
    Identifier of the legal rule that triggered this check result.
    Example: "CA-7yr-felony"

  - `results.cases.checks.rule_type` (string)
    The type of rule that was applied:
- legal: A rule based on statutory or regulatory requirements
- policy: A rule based on company policy
    Enum: "legal", "policy"

  - `results.cases.checks.domain` (string)
    The filter domain in which this rule was applied.
    Example: "employment"

  - `results.cases.checks.description` (string)
    Human-readable description of what the legal rule evaluated.
    Example: "Felony convictions older than 7 years cannot be reported in California"

  - `results.cases.checks.run_at` (string)
    The timestamp when this check was evaluated.
    Example: "2024-01-15T10:30:00.000Z"

  - `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.state` (string)
    A two-letter US state code.

  - `results.checks` (array)
    Legal annotation check results for this record.

  - `check_type` (string)
    The type of regulated check. Currently only instant_criminal_regulated is supported.
    Enum: "instant_criminal_regulated"

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

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

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