openapi: 3.1.0
info:
  title: Checkr Trust API
  version: '1.0'
  summary: >
    Checkr Trust is a modern, RESTful API-driven service designed to enhance
    trust and safety for your platform. The Checkr Trust API uses
    resource-oriented URLs, supports HTTPS for authentication and requests, and
    returns JSON responses.


    The Checkr Trust API provides access to a rich set of data, including
    criminal records, traffic infractions, and registry checks. Once
    credentialed, you can start testing locally in minutes.


    ## Intended Use Cases


    Important: Checkr Trust is not a “consumer reporting agency” or otherwise a
    producer of “consumer reports,” as those terms are defined in the Fair
    Credit Reporting Act (“FCRA”). Checkr Trust data must not be accessed,
    obtained, disclosed, or otherwise used to make any decisions related to
    credit, insurance, employment, or any other purposes described in 15 U.S.C.
    § 1681b of FCRA
  contact:
    name: API Development Team
    email: checkr-trust@checkr.com
    url: https://checkrtrust.com
  license:
    name: Proprietary
    url: https://checkrtrust.com
servers:
  - url: https://api.checkrtrust.com/v1
    description: Checkr Trust API
security:
  - get-bearer-token-using-oauth2: []
x-tagGroups:
  - name: Resources
    tags:
      - Accounts
      - Instant Checks
      - Criminal Checks
      - County Checks
      - Driver Checks
      - Identity Verifications
      - Profiles
      - Regulated Checks
      - Regulated Criminal Reports
tags:
  - name: Accounts
    description: >-
      Endpoints and operations having to do with accounts and authorization.
      Account creation and credentialing will be done with a Checkr Trust team
      member.
  - name: County Checks
    description: >-
      County Checks provide county-level criminal background check results for a
      specific jurisdiction. Results are retrieved from county court records and
      can be cancelled while in pending status.
  - name: Criminal Checks
    description: >-
      Criminal Checks provide criminal record check results delivered
      asynchronously via webhook.
  - name: Driver Checks
    description: >-
      Driver Checks provide the resulting information relevant to the requested
      driver license. The response will include the driver check type and
      results.
  - name: Identity Verifications
    description: >-
      Identity Verifications provide the resulting information relevant to the
      requested verification for a set of PII. The response will include the IDV
      type and results.
  - name: Instant Checks
    description: >-
      Instant Checks provide the resulting information relevant to the requested
      check for a set of PII. Checks will include the Check type and results.
  - name: Profiles
    description: >-
      Profiles represent a set of Personally Identifiable Information (PII) for
      a person who will be checked. Profiles can be updated with the latest
      information for a person and be referenced to generate checks.
  - name: Regulated Checks
    description: >-
      Regulated Checks provide instant criminal record check results with legal
      annotation. Results include checks at the record, case, and charge levels
      indicating compliance with applicable legal rules. A permissible purpose
      is required for FCRA compliance.
  - name: Regulated Criminal Reports
    description: >-
      Regulated Criminal Reports provide asynchronous criminal record check
      results with legal annotation. Results are delivered via webhook once
      processing is complete. A permissible purpose is required for Fair Credit
      Reporting Act (FCRA) compliance.
paths:
  /accounts/token:
    post:
      summary: Create token
      description: >-
        Get a bearer token which will allow you to access the other endpoints in
        this API
      tags:
        - Accounts
      requestBody:
        $ref: '#/components/requestBodies/post-token-request-body'
      responses:
        '201':
          $ref: '#/components/responses/post-token-response-body'
        '401':
          $ref: '#/components/responses/post-token-unauthorized-response-body'
      operationId: post-accounts-token
      security: []
  /checks:
    get:
      summary: Get checks
      description: Get a set of checks
      tags:
        - Instant Checks
      parameters:
        - description: limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-checks
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create check
      description: Create a new check
      tags:
        - Instant Checks
      parameters:
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      requestBody:
        $ref: '#/components/requestBodies/post-check-request-body'
      responses:
        '201':
          description: >
            Created.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      operationId: post-checks
      security:
        - get-bearer-token-using-oauth2: []
  /checks/{check_id}:
    get:
      summary: Get check
      description: Get a single check with a given id
      tags:
        - Instant Checks
      parameters:
        - description: the uuid identifying the check
          $ref: '#/components/parameters/check_id'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-check-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /driver_checks:
    get:
      summary: Get driver checks
      description: Get a set of previously created driver checks
      tags:
        - Driver Checks
      parameters:
        - description: limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                    - $ref: '#/components/schemas/driver_check_driver_license_status'
                    - $ref: '#/components/schemas/driver_check_motor_vehicle_report'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '409':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-driver-check
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create driver check
      description: >
        Create a new driver check.


        For `motor_vehicle_report` checks in Washington (`WA`), only DPPA
        purposes `employment` and `insurance` are supported.

        If your account is configured with a different DPPA purpose, requests
        for `motor_vehicle_report` checks in `WA` will be rejected.

        This restriction does not apply to `driver_license_status` checks.
      tags:
        - Driver Checks
      requestBody:
        $ref: '#/components/requestBodies/post-driver-check-request-body'
      responses:
        '201':
          description: >
            Created.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/driver_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      callbacks:
        onSearchCompleted:
          https://example.com/my-webhook-endpoint:
            post:
              summary: Driver Check Completion Webhook
              description: >
                Callback (webhook) triggered when the driver check search is
                finished. 


                Driver check clients must configure this webhook URL when their
                account is set up via their Checkr Trust Account Executive. 


                The payload contains the results for either
                `driver_license_status` or `motor_vehicle_report` checks,
                depending on what was initiated. See the schemas below for
                details.


                Refer to the main [Webhooks](../index.md#webhooks) documentation
                for details on signature verification.
              requestBody:
                description: Payload containing the driver check results
                content:
                  application/json:
                    schema:
                      oneOf:
                        - $ref: >-
                            #/components/schemas/driver-license-status-completed-event-body
                        - $ref: >-
                            #/components/schemas/motor-vehicle-report-completed-event-body
              responses:
                2xx:
                  description: >
                    Return any 2xx status (e.g. 200 OK, 201 Created, 204 No
                    Content) when you successfully process the callback.

                    We treat any 2xx as success and will not retry the POST.
                4xx:
                  description: >
                    HTTP status codes in the 4xx range indicate client errors
                    (e.g., 400 Bad Request, 401 Unauthorized).

                    Returning a 4xx status may result in retries depending on
                    the specific status code.
      operationId: post-driver-checks
      security:
        - get-bearer-token-using-oauth2: []
  /driver_checks/{driver_check_id}:
    get:
      summary: Get driver check
      description: Get a previously created driver check with a given id
      tags:
        - Driver Checks
      parameters:
        - description: the uuid identifying the driver check
          $ref: '#/components/parameters/driver_check_id'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/driver_check_driver_license_status'
                  - $ref: '#/components/schemas/driver_check_motor_vehicle_report'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-driver-check-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /identity_verifications:
    get:
      summary: Get identity verifications
      description: Get a set of identity verifications
      tags:
        - Identity Verifications
      parameters:
        - description: limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/identity_verification'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-identity-verifications
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create identity verification
      description: Create a new identity verification
      tags:
        - Identity Verifications
      requestBody:
        $ref: '#/components/requestBodies/post-identity-verification-request-body'
      parameters:
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '201':
          description: >
            Created.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/identity_verification_post_response'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      operationId: post-identity-verifications
      security:
        - get-bearer-token-using-oauth2: []
      callbacks:
        onDocumentVerificationCompleted:
          https://example.com/my-webhook-endpoint:
            post:
              summary: >-
                Callback (webhook) triggered when document verification is
                completed.
              description: >-
                This callback is invoked when an identity verification of type
                'document_verification' reaches a final state (complete, failed,
                etc.). The URL is pre-configured for the client account.
              requestBody:
                description: >-
                  Payload containing the completed document verification
                  details.
                content:
                  application/json:
                    schema:
                      $ref: >-
                        #/components/schemas/document-verification-completed-event-body
              responses:
                2xx:
                  description: >
                    Return any 2xx status (e.g. 200 OK, 201 Created, 204 No
                    Content) when you successfully process the callback.

                    We treat any 2xx as success and will not retry the POST.
                4xx:
                  description: >
                    If your webhook handler returns a 4xx or 5xx status, we will
                    retry the POST a set number of times (with exponential
                    backoff).
  /identity_verifications/{identity_verification_id}:
    get:
      summary: Get identity verification
      description: Get a single identity verification with a given id
      tags:
        - Identity Verifications
      parameters:
        - description: the uuid identifying the identity verification
          $ref: '#/components/parameters/identity_verification_id'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/identity_verification'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-identity-verification-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /identity_verifications/{identity_verification_id}/files:
    get:
      summary: Download collected document images
      description: >
        (Document Verification only) Download a ZIP of collected images for the
        specified identity verification. 

        The ZIP contains the following files:

        - Doc_Selfie_1_blob.jpg - the selfie image

        - documentbackDoc_Back_1_blob.jpg - the document back image

        - documentfrontDoc_Front_1_blob.jpg - the document front image
      tags:
        - Identity Verifications
      parameters:
        - description: the uuid identifying the identity verification
          $ref: '#/components/parameters/identity_verification_id'
      responses:
        '200':
          description: ZIP file
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '422':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
        '502':
          $ref: '#/components/responses/error'
      operationId: get-identity-verification-files
      security:
        - get-bearer-token-using-oauth2: []
  /profiles:
    get:
      summary: Get profiles
      description: Get a set of profiles
      tags:
        - Profiles
      parameters:
        - description: limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_checks:
              summary: Include the checks in the response
              value:
                - checks
              description: >-
                Including the checks parameter will embed the full check objects
                in place of the check_ids
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/profile'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-profiles
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create profile
      description: >
        Create a new profile with personally identifiable information (PII).


        The profile can include various identity fields (SSN, email, phone)
        which are used for identity verification

        and record matching in check products. The more identity fields
        provided, the better

        the matching and verification capabilities will be.
      tags:
        - Profiles
      requestBody:
        $ref: '#/components/requestBodies/post-profile-request-body'
      parameters:
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_checks:
              summary: Include the checks in the response
              value:
                - checks
              description: >-
                Including the checks parameter will embed the full check objects
                in place of the check_ids
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/profile'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: post-profiles
      security:
        - get-bearer-token-using-oauth2: []
  /profiles/{profile_id}:
    get:
      summary: Get profile
      description: Get a single profile with a given id
      tags:
        - Profiles
      parameters:
        - description: the uuid identifying the profile
          $ref: '#/components/parameters/profile_id'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_checks:
              summary: Include the checks in the response
              value:
                - checks
              description: >-
                Including the checks parameter will embed the full check objects
                in place of the check_ids
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/profile'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-profile-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /regulated/checks:
    get:
      summary: Get regulated checks
      description: Get a set of regulated checks for the authenticated account.
      tags:
        - Regulated Checks
      parameters:
        - description: Limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: Skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/regulated_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-regulated-checks
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create regulated check
      description: >
        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.
      tags:
        - Regulated Checks
      parameters:
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
      requestBody:
        $ref: '#/components/requestBodies/post-regulated-check-request-body'
      responses:
        '201':
          description: >
            Created.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regulated_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      operationId: post-regulated-checks
      security:
        - get-bearer-token-using-oauth2: []
  /regulated/checks/{check_id}:
    get:
      summary: Get regulated check
      description: Get a single regulated check with a given id.
      tags:
        - Regulated Checks
      parameters:
        - description: The uuid identifying the check
          $ref: '#/components/parameters/check_id'
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regulated_check'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-regulated-check-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /regulated/criminal_reports:
    get:
      summary: Get regulated criminal reports
      description: Get a set of regulated criminal reports for the authenticated account.
      tags:
        - Regulated Criminal Reports
      parameters:
        - description: Limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: Skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/regulated_criminal_report'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-regulated-criminal-reports
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create regulated criminal report
      description: >
        Create a new regulated criminal report with legal annotation.


        This endpoint creates an asynchronous criminal report that 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 Fair Credit
        Reporting Act (FCRA) requirements.


        **Important Notes:**

        - Results are NOT returned in the HTTP response (returns 202 Accepted)

        - Full results are delivered asynchronously via webhook once processing
        is complete
      tags:
        - Regulated Criminal Reports
      requestBody:
        $ref: '#/components/requestBodies/post-regulated-criminal-report-request-body'
      responses:
        '202':
          description: >
            Accepted - Report created, results will be delivered via webhook.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regulated_criminal_report_created'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      operationId: post-regulated-criminal-reports
      security:
        - get-bearer-token-using-oauth2: []
  /regulated/criminal_reports/{id}:
    get:
      summary: Get regulated criminal report
      description: Get a single regulated criminal report with a given id.
      tags:
        - Regulated Criminal Reports
      parameters:
        - description: The uuid identifying the regulated criminal report
          name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 2b8313e8-4efd-45a1-b578-952b8313e890
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regulated_criminal_report'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-regulated-criminal-report-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /county_checks:
    post:
      summary: Create county check
      description: >
        Create a new county criminal check for a specific county jurisdiction.


        This endpoint initiates a county-level criminal background check using
        either

        provided PII (personally identifiable information) or an existing
        profile.


        Required fields when providing PII (without profile_id):

        - first_name

        - last_name

        - dob

        - state

        - county_fips_code


        When using a profile_id, only state and county_fips_code are required.
      tags:
        - County Checks
      parameters:
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      requestBody:
        $ref: '#/components/requestBodies/post-county-check-request-body'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/county_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
        '502':
          $ref: '#/components/responses/error'
      operationId: post-county-checks
      security:
        - get-bearer-token-using-oauth2: []
  /county_checks/{county_check_id}:
    get:
      summary: Get county check
      description: Get a single county check with a given id.
      tags:
        - County Checks
      parameters:
        - description: The uuid identifying the county check
          $ref: '#/components/parameters/county_check_id'
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/county_check'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-county-check-by-id
      security:
        - get-bearer-token-using-oauth2: []
  /county_checks/{county_check_id}/cancel:
    post:
      summary: Cancel county check
      description: |
        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.
      tags:
        - County Checks
      parameters:
        - description: The uuid identifying the county check
          $ref: '#/components/parameters/county_check_id'
        - description: Include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
      requestBody:
        $ref: '#/components/requestBodies/post-county-check-cancel-request-body'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/county_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
        '502':
          $ref: '#/components/responses/error'
      operationId: post-county-check-cancel
      security:
        - get-bearer-token-using-oauth2: []
  /criminal_checks:
    get:
      summary: Get criminal checks
      description: >-
        Get a set of criminal checks. Results are only available after webhook
        delivery.
      tags:
        - Criminal Checks
      parameters:
        - description: limit the number of records returned
          $ref: '#/components/parameters/limit'
        - description: skip a number of records before returning (for paging)
          $ref: '#/components/parameters/skip'
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
          examples:
            include_profile:
              summary: Include the profile in the response
              value:
                - profile
              description: >-
                Including the profile parameter will embed the full profile
                object in place of the profile_id
            include_results_found:
              summary: Include results_found boolean
              value:
                - results_found
              description: >-
                Including results_found will return a boolean indicating if
                results were found instead of the full results array
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/criminal_check'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-criminal-checks
      security:
        - get-bearer-token-using-oauth2: []
    post:
      summary: Create criminal check
      description: >
        Create a new criminal check. The check runs synchronously but results
        are only delivered via webhook.


        **Important Notes:**

        - Results are NOT returned in the HTTP response (returns 202 Accepted)

        - Results are delivered asynchronously via webhook

        - Webhook destination_url must be configured in product configuration
      tags:
        - Criminal Checks
      parameters:
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      requestBody:
        $ref: '#/components/requestBodies/post-criminal-check-request-body'
      responses:
        '202':
          description: >
            Accepted - Check created, results will be delivered via webhook.

            When the product has usage limits configured, the response includes
            X-RateLimit-Limit, X-RateLimit-Remaining, and optionally
            X-RateLimit-Expires.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The ID of the created check
                  status:
                    type: string
                    enum:
                      - pending
                    description: Status of the check (always 'pending' on creation)
                  created_at:
                    type: string
                    format: date-time
                    description: Timestamp when the check was created
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '429':
          $ref: '#/components/responses/rate-limit-exceeded'
        '500':
          $ref: '#/components/responses/error'
      callbacks:
        onSearchCompleted:
          https://example.com/my-webhook-endpoint:
            post:
              summary: Criminal Check Completion Webhook
              description: >
                Callback (webhook) triggered when the criminal check search is
                finished. 


                Criminal check clients must configure this webhook URL in their
                product configuration settings when their account is set up via
                their Checkr Trust Account Executive. 


                The payload contains the results for the `criminal_check`.
                Results are delivered asynchronously via webhook. See the schema
                below for details.


                Refer to the main [Webhooks](../index.md#webhooks) documentation
                for details on signature verification.
              requestBody:
                description: Payload containing the criminal check results
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/criminal-check-completed-event-body'
              responses:
                2xx:
                  description: >
                    Return any 2xx status (e.g. 200 OK, 201 Created, 204 No
                    Content) when you successfully process the callback.

                    We treat any 2xx as success and will not retry the POST.
                4xx:
                  description: >
                    HTTP status codes in the 4xx range indicate client errors
                    (e.g., 400 Bad Request, 401 Unauthorized).

                    Returning a 4xx status may result in retries depending on
                    the specific status code.
      operationId: post-criminal-checks
      security:
        - get-bearer-token-using-oauth2: []
  /criminal_checks/{criminal_check_id}:
    get:
      summary: Get criminal check
      description: >-
        Get a single criminal check with a given id. Results are only visible
        after webhook delivery.
      tags:
        - Criminal Checks
      parameters:
        - description: the uuid identifying the criminal check
          name: criminal_check_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - description: include related resources in the response
          $ref: '#/components/parameters/include'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/criminal_check'
        '401':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '500':
          $ref: '#/components/responses/error'
      operationId: get-criminal-check-by-id
      security:
        - get-bearer-token-using-oauth2: []
components:
  parameters:
    limit:
      name: limit
      description: limit the number of records returned
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 999999
        default: 10
    skip:
      name: skip
      description: skip a number of records before returning (for paging)
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 999999
        default: 0
    include:
      name: include
      description: include related resources in the response
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
    check_id:
      name: check_id
      description: the uuid identifying the check
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2b8313e8-4efd-45a1-b578-952b8313e890
    driver_check_id:
      name: driver_check_id
      description: the uuid identifying the driver check
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2b8313e8-4efd-45a1-b578-952b8313e890
    identity_verification_id:
      name: identity_verification_id
      description: the uuid identifying the identity verification
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2b8313e8-4efd-45a1-b578-952b8313e890
    profile_id:
      name: profile_id
      description: the uuid identifying the profile
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2b8313e8-b578-45a1-4efd-952b8313e890
    county_check_id:
      name: county_check_id
      description: the uuid identifying the county check
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 2b8313e8-4efd-45a1-b578-952b8313e890
  schemas:
    uuid:
      type: string
      format: uuid
      description: A universally unique identifier (UUID) in standard format.
      example: 2b8313e8-4efd-45a1-b578-952b8313e890
    datetime:
      type: string
      format: date-time
      description: An ISO 8601 formatted date-time string.
      example: '2020-01-01T00:00:00Z'
    date:
      type: string
      format: date
      description: An ISO 8601 formatted date string.
      example: '2020-01-01'
    date_string_complete:
      description: A date in the form YYYYMMDD.
      type: string
      pattern: \d{8}
      minLength: 8
      maxLength: 8
      example: '19950401'
    date_string_partial:
      description: >
        A date or partial date in the form YYYYMMDD.

        Since some dates are partial, they may be represented as YYYY0000 or
        0000MMDD or YYYYMM00.
      type: string
      pattern: \d{8}
      minLength: 8
      maxLength: 8
      example: '19950401'
    country_code:
      type: string
      pattern: ^[A-Z]{2}$
      description: A two-letter country code in ISO 3166-1 alpha-2 format.
      example: US
    state_code:
      type: string
      pattern: ^[A-Z]{2}$
      description: A two-letter US state code.
      example: CA
    zip_code:
      type: string
      pattern: ^\d{5}(-\d{4})?$
      description: US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).
      example: '94105'
    address:
      type: object
      description: A physical address in the United States.
      properties:
        street:
          type: string
          description: >-
            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
        city:
          type: string
          description: The name of the city or municipality.
          example: Frankfort
        state:
          description: The two-letter US state code where the address is located.
          $ref: '#/components/schemas/state_code'
        zip_code:
          description: The US postal ZIP code for the address.
          $ref: '#/components/schemas/zip_code'
        country:
          description: >-
            The two-letter country code, typically "US" for United States
            addresses.
          $ref: '#/components/schemas/country_code'
      required:
        - street
        - city
        - state
        - zip_code
    email_string:
      type: string
      format: email
      description: An email address.
      example: john.doe@example.com
    phone_string:
      type: string
      pattern: ^\+[1-9]\d{1,14}$
      description: >
        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".
      example: '+14155552671'
    ssn_string:
      type: string
      pattern: ^\d{3}-?\d{2}-?\d{4}$
      description: A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.
      example: 123-45-6789
    custom_id_string:
      type: string
      pattern: ^[a-zA-Z0-9_-]{1,64}$
      description: >-
        An identifier of your choice, if you wish to use one. Limited to 64
        alphanumeric characters, underscores, and hyphens.
      example: my-custom-id-123
    reference_id:
      type: string
      pattern: ^[a-zA-Z0-9_-]{1,64}$
      description: >-
        A reference identifier for linking related records. Limited to 64
        alphanumeric characters, underscores, and hyphens.
      example: ref-123
    ruleset_id:
      description: >-
        Identifier of an existing ruleset containing filtering rules. To set up
        account rulesets, please reach out to your Checkr Trust Account
        Executive or Customer Success representative to set up the
        configuration.
      type: string
      format: uuid
      example: d16e88e6-aacc-4c42-9cd2-58a93dc9d8af
    ruleset_ids:
      description: >
        A list of ruleset identifiers to apply. When both `ruleset_id` and

        `ruleset_ids` are provided, they are merged and de-duplicated before
        applying.
      type: array
      items:
        $ref: '#/components/schemas/ruleset_id'
    profile_id:
      type: string
      format: uuid
      description: Identifier of an existing profile containing search criteria.
      example: 2b8313e8-4efd-45a1-b578-952b8313e890
    input_type:
      title: input_type
      type: string
      description: >-
        The type of input being provided for the search. Can be either a
        person's information or an address.
      enum:
        - person
        - address
      default: person
    input_type_address:
      title: input_type
      type: string
      description: >-
        Specifies that the input type is an address. Used when searching by
        address only.
      enum:
        - address
    source_states:
      description: >
        An array of state abbreviations. Only records which come from a given
        source state are included in the results. Note that some sources are not
        tagged as coming from a single source state, so records from those
        sources will always be included. Sex offender registry records and most
        watchlist records are not tagged with a source state, and so will appear
        in the results regardless of this flag.  
      type: array
      items:
        $ref: '#/components/schemas/state_code'
    order_by:
      title: order_by
      type: string
      description: >-
        Specifies the field to sort the results by. Currently only supported for
        'photo_urls'.
      enum:
        - photo_urls
      example: photo_urls
    error:
      type: object
      description: A standard error object following JSON:API error format.
      properties:
        code:
          type: string
          description: A machine-readable error code.
          example: invalid_request
        title:
          type: string
          description: A human-readable error title.
          example: Invalid Request
        source:
          type: object
          description: An object containing references to the source of the error.
          properties:
            pointer:
              type: string
              description: >-
                A JSON Pointer [RFC6901] to the associated entity in the request
                document.
              example: /data/attributes/first_name
      required:
        - code
        - title
    errors:
      type: array
      description: An array of error objects.
      items:
        $ref: '#/components/schemas/error'
    token:
      type: object
      description: An OAuth 2.0 access token response.
      properties:
        access_token:
          type: string
          description: The JWT access token to use for API requests.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        token_type:
          type: string
          description: The type of token, always "Bearer".
          example: Bearer
        expires_in:
          type: integer
          description: The number of seconds until the token expires.
          example: 3600
        scope:
          type: string
          description: The permissions that this token grants.
          example: read:account create:account delete:account
    profile_fields:
      type: object
      description: Common fields used across profile-related schemas.
      properties:
        first_name:
          description: The first name of the person.
          type: string
        middle_name:
          description: The middle name of the person. Can be null if not provided.
          type: string
        last_name:
          description: The last name of the person.
          type: string
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        phone:
          description: >-
            A phone number in the form +[country code][number including area
            code]. (E.164 format)
          $ref: '#/components/schemas/phone_string'
        email:
          $ref: '#/components/schemas/email_string'
        ssn:
          $ref: '#/components/schemas/ssn_string'
        address:
          $ref: '#/components/schemas/address'
        custom_id:
          $ref: '#/components/schemas/custom_id_string'
        driver_license_state:
          $ref: '#/components/schemas/state_code'
        driver_license_number:
          type: string
          description: The driver license number. Format dependent on State.
          example: D1234567
    profile:
      title: profile
      description: >-
        A profile containing personal information used for checks and
        verifications.
      type: object
      allOf:
        - properties:
            id:
              $ref: '#/components/schemas/profile_id'
        - $ref: '#/components/schemas/profile_fields'
    record_category:
      description: >
        A categorization of the type of record returned.

        Maps closely to the source category, except PA sources can contain
        either Patriot or Registry records.
      type: string
      enum:
        - arrest
        - Criminal/traffic
        - Warrant
        - Sex Offender
        - Patriot
        - Registry
      x-enumDescriptions:
        arrest: arrest record (includes jail/prison records)
        Criminal/traffic: criminal record (includes traffic records)
        Warrant: warrant record
        Sex Offender: sex offender list record
        Patriot: watchlist records
        Registry: >-
          registry records (not necessarily implying wrongdoing, so excluded by
          default)
      example: Criminal/traffic
    charge_type:
      description: the type (level, severity) of a charge
      type: string
      title: category
      enum:
        - felony
        - misdemeanor
        - petty_offense
        - unknown
      example: petty_offense
    charge_category:
      description: the highest level of categorization of a charge
      type: string
      title: category
      enum:
        - Criminal Intent
        - Drugs & Alcohol
        - Fraud & Deception
        - Homicide
        - Security
        - Sexual
        - Statutory
        - Theft & Property
        - Vehicles & Traffic
        - Violence
        - unclassified
      example: Theft & Property
    charge_subcategory:
      description: the second level of categorization of a charge
      type: string
      title: subcategory
      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
      example: Petty Theft
    charge_subsubcategory:
      description: |
        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.
      type: string
      title: subsubcategory
      example: Retail Theft
    sentence:
      type: object
      properties:
        conviction_date:
          $ref: '#/components/schemas/date_string_partial'
        details:
          description: Description of the sentence, if any
          type: string
          example: fine, 1D
    disposition_type:
      description: the type of disposition
      type: string
      enum:
        - Conviction
        - Dismissed
        - Invalid
        - Merged
        - Pending
        - Transferred
        - Warrant
        - Unclassified
      example: Conviction
    disposition:
      type: object
      properties:
        disposition:
          description: A description of the disposition, as provided by the court, if any.
          type: string
          example: GLT
        disposition_date:
          $ref: '#/components/schemas/date_string_partial'
        disposition_type:
          $ref: '#/components/schemas/disposition_type'
    charge:
      type: object
      properties:
        description:
          description: >-
            The description of the offense, as reported on the record.  Format
            varies.
          type: string
          example: SHOPLIFTING
        offense_date:
          $ref: '#/components/schemas/date_string_partial'
        legal_code:
          description: Legal code (statute) as reported by the court or arresting agency.
          type: string
          example: '433.234'
        type:
          $ref: '#/components/schemas/charge_type'
        category:
          $ref: '#/components/schemas/charge_category'
        subcategory:
          $ref: '#/components/schemas/charge_subcategory'
        subsubcategory:
          $ref: '#/components/schemas/charge_subsubcategory'
        record_date:
          description: >
            Date of the record.

            This is not part of the record itself.

            It is a field calculated by Checkr Trust.

            It is the field used to determine if the charge is within the
            lookback period.

            Although there are many other situations, often a convicted charge
            has a

            record_date which is the disposition_date, and a non-conviction
            charge

            has a record_date which is the filing date.
          $ref: '#/components/schemas/date_string_partial'
        city:
          description: The name of the city where the person was charged
          type: string
          example: Indian Hills
        county:
          description: The name of the county where the person was charged
          type: string
          example: Jefferson
        state:
          description: The state where the person was charged
          type: string
          example: KY
        sentences:
          type: array
          items:
            $ref: '#/components/schemas/sentence'
        dispositions:
          type: array
          items:
            $ref: '#/components/schemas/disposition'
    case:
      type: object
      properties:
        case_number:
          description: >-
            The case number assigned by a court.  Not present for records which
            are not from a court.  Format varies.
          type: string
          example: 2025-99999
        type:
          description: >-
            The case type as reported by the court.  Not present for records
            which are not from a court.  Format varies.
          type: string
        status:
          description: >-
            The case status as reported by the court.  Sparsely available. 
            Format varies.
          type: string
        file_date:
          description: >-
            The date the case was filed as reported by the court.  Not present
            for records which are not from a court.
          $ref: '#/components/schemas/date_string_partial'
        arresting_agency:
          description: The name of the arresting agency.
          type: string
          example: Franklin County Sheriff
        arrest_date:
          description: The date the person was arrested.
          $ref: '#/components/schemas/date_string_partial'
        court_name:
          description: The name of the charging court.
          type: string
          example: Franklin County Circuit Court
        court_county:
          description: The county of the charging court.
          type: string
          example: Franklin
        charges:
          description: >-
            Only fields that have a value are returned.  Most charges will have
            only a subset of these fields.
          type: array
          items:
            $ref: '#/components/schemas/charge'
    source_category:
      description: >
        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.
      type: string
      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
      x-enumDescriptions:
        arrest: >-
          The source contains arrest records, typically from a sheriff's
          department or police department.
        court: >-
          The source is a municipal, county, or state court, or administrative
          office of courts (AOC).
        criminal registry: The source is a registry of violent or drug offenders
        DOC: >-
          The source is a local police jail, or state prison (DOC means
          Department of Correction.)
        warrant: >-
          The source is one which has requested the arrest of a person,
          typically a police department.
        sex offender registry: >-
          The source is a registry of sex offenders.  Typically at the state
          level.
        domestic watchlist: The source is a US-based list of some sort of offender.
        foreign watchlist: The source is a US-based list of some sort of offender, e.g. Interpol.
        healthcare registry: >-
          The source is a list of medical professionals in some capacity, and
          does not imply wrongdoing. (Excluded by default.)
        healthcare sanctions: >-
          The source is a list of medical professionals in some capacity, and
          implies wrongdoing.
        financial registry: >-
          The source is a list of financial professionals in some capacity, and
          does not imply wrongdoing. (Excluded by default.)
        financial sanctions: >-
          The source is a list of financial professionals in some capacity, and
          implies wrongdoing.
        other registry: >-
          The source is a list of people, and does not imply wrongdoing.
          (Excluded by default.)
        other sanctions: The source is a list of people, and implies wrongdoing.
        PEP registry: >-
          The source is a list of politically exposed people (e.g. politicians
          and world leaders) who potentially could be bribed or coerced into
          wrongdoing. (Excluded by default.)
      example: court
    source:
      type: object
      properties:
        id:
          description: >-
            An identifier for the source.  E.g. "cookil" or
            "NJ_Supreme_Ct_view".  Can be used to programmatically exclude a
            source.
          type: string
          example: ARSTfranklinKY
        category:
          $ref: '#/components/schemas/source_category'
          example: arrest
        name:
          description: A human-understandable (English) name of the source.
          type: string
          example: KY Franklin County Inmates
        county:
          description: The name of the county (if any) where the record came from.
          type: string
          example: Franklin
        state:
          $ref: '#/components/schemas/state_code'
    record:
      title: record
      type: object
      properties:
        category:
          $ref: '#/components/schemas/record_category'
        person:
          type: object
          properties:
            first_name:
              type: string
              example: John
            middle_name:
              description: middle initial or name or names
              type: string
              example: W
            last_name:
              type: string
              example: Smith
            suffix:
              type: string
            full_name:
              type: string
              example: Smith, John W.
            dob:
              $ref: '#/components/schemas/date_string_partial'
            inferred_dob:
              description: >
                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.
              $ref: '#/components/schemas/date_string_complete'
            doc_number:
              description: >
                Dept. of Corrections number.

                A number or identifier given by a state Dept. of Corrections to
                identify a person who went to prison.
              type: string
            gender:
              description: >-
                The gender, if any, as recorded by the source.  No specific
                format.
              type: string
              example: M
            height:
              description: >-
                The height, if any, as recorded by the source.  No specific
                format.
              type: string
              example: '601'
            weight:
              description: >-
                The weight, if any, as recorded by the source.  No specific
                format.
              type: string
              example: '180'
            hair_color:
              description: >-
                The hair color, if any, as recorded by the source.  No specific
                format.
              type: string
              example: BRN
            eye_color:
              description: >-
                The eye color if any, as recorded by the source.  No specific
                format.
              type: string
              example: HAZ
            skin_color:
              description: >-
                The skin color, if any, as recorded by the source.  No specific
                format.
              type: string
              example: wht
            race:
              description: The race as defined by the source.  No specific format.
              type: string
              example: W
            ethnicity:
              description: >-
                The ethnicity, if any, as recorded by the source.  No specific
                format.
              type: string
              example: Hispanic-American
            physical_build:
              description: >-
                The physical build, if any, as recorded by the source.  No
                specific format.
              type: string
              example: BROAD
            physical_marks:
              description: >-
                Scars, marks, and tattoos as defined by the source.  No specific
                format.
              type: string
              example: blue cross on outside left ankle
            photo_urls:
              description: >-
                A set of URLs referencing pictures of this person, as recorded
                by the source.
              type: array
              items:
                description: >
                  A public URL which has an image, as recorded by the source.

                  Sometimes, the picture is an image which shows the text "No
                  Image Available."

                  We are working on removing those, but you may still encounter
                  them.
                type: string
                format: uri
            name_aliases:
              description: Other names that this person may have gone by.
              type: array
              items:
                type: string
                example: Johnny Smith
            dob_aliases:
              description: Other dates of birth that this person may have used.
              type: array
              items:
                type: string
                example: '19940321'
            addresses:
              description: Addresses that are recorded for this person on this record.
              type: array
              items:
                $ref: '#/components/schemas/address'
        cases:
          description: >-
            Only fields that have a value are returned.  Most cases will have
            only a subset of these fields.
          type: array
          items:
            $ref: '#/components/schemas/case'
        source:
          $ref: '#/components/schemas/source'
    check_type:
      type: string
      enum:
        - instant_criminal
        - sex_offender_registry
    check:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          $ref: '#/components/schemas/datetime'
        results:
          description: When there are no results found, this will be an empty array.
          type: array
          items:
            $ref: '#/components/schemas/record'
        check_type:
          $ref: '#/components/schemas/check_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        run_notes:
          description: >
            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.
          type: array
          items:
            type: string
            example: changed last_name from 'Smith Jr' to 'Smith'
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
          title: check with profile id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
          title: check with profile object
    address_request:
      description: >
        An address to be searched for records.

        - In searching by address, records are matched by street number, street
        name, city, and state

        - Unit/apartment numbers are not used for matching addresses

        - Street types (Avenue, Street, Boulevard) are not used for matching
        addresses

        - For example, "123 Main St., Apt. 3B" will match using "123" and "Main"
      type: object
      properties:
        street:
          description: >
            The street part of the address.

            - Unit/apartment numbers are not used for matching addresses

            - Street types (Avenue, Street, Boulevard) are not used for matching
            addresses

            - For example, "123 Main St., Apt. 3B" will match using "123" and
            "Main"
          type: string
          example: 123 Main St
        city:
          type: string
          description: >-
            The name of the city or municipality where records should be
            searched.
          example: San Francisco
        state:
          description: The two-letter US state code where records should be searched.
          $ref: '#/components/schemas/state_code'
        zip_code:
          description: The US postal ZIP code for the address.
          $ref: '#/components/schemas/zip_code'
        country:
          description: >-
            The two-letter country code, typically "US" for United States
            addresses.
          $ref: '#/components/schemas/country_code'
      required:
        - street
        - city
        - state
        - zip_code
    check-request-from-pii:
      type: object
      properties:
        check_type:
          $ref: '#/components/schemas/check_type'
        input_type:
          $ref: '#/components/schemas/input_type'
        first_name:
          description: >-
            first name (given name).  Do not include prefixes, like "Ms." or
            "Dr."
          type: string
          example: Jane
        middle_name:
          description: middle name(s)
          type: string
          example: Mary Louise
        last_name:
          description: last name (surname).  Do not include suffixes, like "Jr." or "2nd".
          type: string
          example: O'Donnell-Van Helsing
        full_name:
          description: >
            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,

            and then use those for the check.

            If you already know the first and last names, we suggest sending
            them.

            The parser will attempt to remove prefixes and suffixes, and handles
            several different formats of name,

            but we cannot guarantee it will parse the name in the manner you
            expect.
          type: string
          example: O'Donnell-Van Helsing, Dr. Jane Mary Louise, MD
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        ssn:
          description: >-
            Social Security Number used for additional identity verification and
            record matching
          $ref: '#/components/schemas/ssn_string'
        phone:
          $ref: '#/components/schemas/phone_string'
        addresses:
          description: >
            An array of addresses to search for criminal records.

            When provided, records will be matched against any of the addresses
            in the array.
          type: array
          items:
            $ref: '#/components/schemas/address_request'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
        order_by:
          $ref: '#/components/schemas/order_by'
      required:
        - first_name
        - last_name
      example:
        first_name: JOHN
        last_name: SMITH
        dob: '19900101'
        ssn: 123-45-6789
        phone: '+14155552671'
        addresses:
          - street: 456 Oak Ave
            city: Los Angeles
            state: CA
            zip_code: '90001'
          - street: 789 Pine Blvd
            city: San Diego
            state: CA
            zip_code: '92101'
    check_type_sex_offender_registry:
      type: string
      title: check_type
      enum:
        - sex_offender_registry
    check-request-from-address:
      description: the request to create a new check using an address
      properties:
        check_type:
          $ref: '#/components/schemas/check_type_sex_offender_registry'
        input_type:
          $ref: '#/components/schemas/input_type_address'
        address:
          $ref: '#/components/schemas/address_request'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
        order_by:
          $ref: '#/components/schemas/order_by'
      required:
        - check_type
        - input_type
        - address
      example:
        check_type: sex_offender_registry
        input_type: address
        address:
          street: 123 Main Street
          city: New York
          state: NY
          zip_code: '12345'
    check-request-from-profile:
      description: the request to create a new check from an existing profile
      properties:
        check_type:
          $ref: '#/components/schemas/check_type'
        input_type:
          $ref: '#/components/schemas/input_type'
        profile_id:
          $ref: '#/components/schemas/profile_id'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
        order_by:
          $ref: '#/components/schemas/order_by'
      required:
        - profile_id
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
    check_type_driver_license_status:
      type: string
      enum:
        - driver_license_status
    driver_check_driver_license_status_result:
      title: driver_license_status_result
      type: object
      properties:
        requested_profile:
          type: object
          allOf:
            - $ref: '#/components/schemas/profile_fields'
          description: >-
            The inputs used to create the driver check. Fields that weren't
            provided will not be included.
        passenger:
          type: object
          properties:
            validity:
              type: string
              enum:
                - VALID
                - INVALID
                - NOT FOUND
              x-enumDescriptions:
                VALID: >-
                  The license number is valid and reflects the authorization to
                  drive a passenger vehicle.
                INVALID: >-
                  The license number is invalid and cannot be used to drive a
                  passenger vehicle.
                NOT FOUND: >-
                  We did not find a definitive result for this license. This
                  could indicate the 'requested_profile' values had an error /
                  typo. Another possibility is that we were unable to determine
                  the 'ssn' and/or 'zip_code' fields, they are required for the
                  requested state, and they weren't provided in the
                  requested_profile.
    driver_check_driver_license_status:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          description: A datetime, or null if not completed.
          oneOf:
            - $ref: '#/components/schemas/datetime'
            - type: 'null'
        results:
          description: Results, or null if not completed.
          oneOf:
            - $ref: '#/components/schemas/driver_check_driver_license_status_result'
            - type: 'null'
        check_type:
          $ref: '#/components/schemas/check_type_driver_license_status'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
            check_type:
              $ref: '#/components/schemas/check_type_driver_license_status'
          title: driver license status with profile id
          required:
            - profile_id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
            check_type:
              $ref: '#/components/schemas/check_type_driver_license_status'
          title: driver license status with profile object
          required:
            - profile
    check_type_motor_vehicle_report:
      type: string
      enum:
        - motor_vehicle_report
    driver_check_result_code:
      type: string
      title: result_code
      enum:
        - FOUND
        - NOT FOUND
        - REJECTED
        - LOCKED
      x-enumDescriptions:
        FOUND: motor vehicle report yielded results
        NOT FOUND: motor vehicle report information yielded no results
        REJECTED: >-
          motor vehicle report information was invalid or an unknown error
          occurred
        LOCKED: the motor vehicle report is not available electronically
    driver_event:
      title: driver_event
      type: object
      properties:
        description:
          type: string
        code:
          type: string
        acd_code:
          type: string
        type:
          type: string
        jurisdiction:
          type: string
        location:
          type: string
        date:
          type: string
        disposition_date:
          type: string
        disposition:
          type: string
        points:
          type: string
        additional_detail:
          type: string
    driver_crash:
      title: driver_crash
      type: object
      properties:
        date:
          $ref: '#/components/schemas/date'
          description: The date the crash occurred
        type:
          type: string
          description: The type of crash
        jurisdiction:
          type: string
          description: The jurisdiction where the crash occurred.
        location:
          type: string
          description: A more specific location of the crash (if provided)
        description:
          type: string
          description: A description of the crash
        severity:
          type: string
          enum:
            - AC0
            - AC1
            - AC2
            - AC3
            - NEW
          x-enumDescriptions:
            AC0: Undeclared
            AC1: Property Damage
            AC2: Injury
            AC3: Fatality
            NEW: Unassigned
        was_citation_issued:
          type: boolean
          description: Whether or not a citation was issued for this crash
        comments:
          type: array
          description: >-
            Information related to the section that could not be associated with
            a named field
          items:
            type: string
    driver_jurisdiction_action:
      title: jurisdiction_action
      type: object
      properties:
        type:
          type: string
          description: >-
            The type of action taken (i.e. suspension, revocation, withdrawal,
            etc.)
        group:
          description: >-
            Removal of Driving Privileges (RDP) Group. This provides additional
            context as to why an action was taken.
          type: string
          pattern: ^RDP[0-9]{2}$
          enum:
            - RDP00
            - RDP01
            - RDP10
            - RDP11
            - RDP20
            - RDP30
            - RDP31
            - RDP32
            - RDP33
            - RDP40
            - RDP50
            - RDP60
            - RDP70
            - RDP71
          x-enumDescriptions:
            RDP00: Unspecified
            RDP01: Unassignable
            RDP10: Alcohol or Drug Influence
            RDP11: Alcohol or Drug Related (Non-Driving)
            RDP20: Cumulative (too many violations)
            RDP30: Other Actions (Unlicensed, Reckless, Hit & Run, etc.)
            RDP31: Driving While Barred
            RDP32: Reckless Driving
            RDP33: Vehicle Use in Prohibited Offenses
            RDP40: Failure to Pay / Failure to Appear
            RDP50: >-
              Financial Responsibilty (no insurance at time of crash,
              cancellation of insurance, etc.)
            RDP60: Non-DMV-Related
            RDP70: DMV-Related
            RDP71: CDL Downgrade
        start_date:
          description: The date the action became effective
          $ref: '#/components/schemas/date'
        end_date:
          description: The date the action is no longer effective
          $ref: '#/components/schemas/date'
        extent_of_action:
          description: The extent of what privileges are affected by this action
          type: string
        description:
          description: A description of the action
          type: string
        initiating_jurisdiction:
          description: The jurisdiction that took or initiated this action
          type: string
          pattern: ^[A-Za-z]{2}$
        comments:
          description: >-
            Information related to the section that could not be associated with
            a named field.
          type: array
          items:
            type: string
    driver_license_type:
      description: >-
        If the license type is PREVIOUS or OUT OF STATE, the rest of the license
        information may not be present.
      type: string
      title: type
      enum:
        - CDL
        - CDL PERMIT
        - MOTORCYCLE
        - MOTORCYCLE PERMIT
        - PASSENGER
        - PASSENGER PERMIT
        - MOPED
        - ID CARD
        - PREVIOUS
        - OUT OF STATE
      example: PASSENGER
    driver_license_validity:
      type: string
      title: validity
      enum:
        - VALID
        - INVALID
        - UNKNOWN
      example: VALID
    driver_license_license_dls:
      title: license
      type: object
      properties:
        type:
          $ref: '#/components/schemas/driver_license_type'
        validity:
          $ref: '#/components/schemas/driver_license_validity'
        jurisdiction:
          description: The jurisdiction that issued the license
          type: string
          pattern: ^[A-Za-z]{2}$
        number:
          description: The license number. Format dependent on State.
          type: string
        class_code:
          description: >-
            Code representing the license class (may not have a value if
            class_description is provided)
          type: string
        class_description:
          description: >-
            Description of the license class (may not have a value if class_code
            is provided)
          type: string
        status_code:
          description: >-
            Code representing the license status (may not have a value if
            status_description is provided)
          type: string
        status_description:
          description: >-
            Description of the license status (may not have a value if
            status_code is provided)
          type: string
        issued_on:
          $ref: '#/components/schemas/datetime'
        expires_on:
          $ref: '#/components/schemas/datetime'
    driver_license_restriction:
      title: restriction
      type: object
      properties:
        code:
          description: Code for the restriction
          type: string
        description:
          description: Description of the restriction
          type: string
        category:
          description: The category of restriction
          type: string
    driver_license_endorsement:
      title: endorsement
      type: object
      properties:
        code:
          description: Code for the endorsement
          type: string
        description:
          description: Description of the endorsement
          type: string
        category:
          description: The category of endorsement
          type: string
    driver_license_license_mvr:
      title: license
      type: object
      allOf:
        - $ref: '#/components/schemas/driver_license_license_dls'
        - type: object
          properties:
            restrictions:
              type: array
              items:
                $ref: '#/components/schemas/driver_license_restriction'
            endorsements:
              type: array
              items:
                $ref: '#/components/schemas/driver_license_endorsement'
            comments:
              description: >-
                Information related to the section that could not be associated
                with a named field
              type: array
              items:
                type: string
    driver_license_miscellaneous:
      title: miscellaneous
      type: object
      properties:
        date:
          description: A date associated with this miscellaneous information (if provided)
          $ref: '#/components/schemas/date'
        description:
          description: A description of the miscellaneous information
          type: string
        comments:
          description: >-
            Information related to the section that could not be associated with
            a named field
          type: array
          items:
            type: string
    driver_check_motor_vehicle_report_result:
      title: motor_vehicle_report_result
      type: object
      properties:
        order_details:
          type: object
          properties:
            result_code:
              $ref: '#/components/schemas/driver_check_result_code'
        driver_information:
          type: object
          properties:
            date_of_birth:
              type: string
            license:
              type: object
              properties:
                number:
                  type: string
                jurisdiction:
                  type: string
            name:
              type: object
              properties:
                first:
                  type: string
                middle:
                  type: string
                last:
                  type: string
                suffix:
                  type: string
                raw:
                  type: string
        driver_events:
          type: array
          items:
            $ref: '#/components/schemas/driver_event'
        crashes:
          type: array
          items:
            $ref: '#/components/schemas/driver_crash'
        jurisdiction_actions:
          type: array
          items:
            $ref: '#/components/schemas/driver_jurisdiction_action'
        licenses:
          type: array
          items:
            $ref: '#/components/schemas/driver_license_license_mvr'
        miscellaneous:
          type: array
          items:
            $ref: '#/components/schemas/driver_license_miscellaneous'
    driver_check_motor_vehicle_report:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          description: A datetime, or null if not completed.
          oneOf:
            - $ref: '#/components/schemas/datetime'
            - type: 'null'
        results:
          description: Results, or null if not completed.
          oneOf:
            - $ref: '#/components/schemas/driver_check_motor_vehicle_report_result'
            - type: 'null'
        profile_id:
          $ref: '#/components/schemas/profile_id'
        profile:
          $ref: '#/components/schemas/profile'
        check_type:
          $ref: '#/components/schemas/check_type_motor_vehicle_report'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
            check_type:
              $ref: '#/components/schemas/check_type_motor_vehicle_report'
          title: motor vehicle report with profile id
          required:
            - profile_id
            - check_type
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
            check_type:
              $ref: '#/components/schemas/check_type_motor_vehicle_report'
          title: motor vehicle report with profile object
          required:
            - profile
    driver_check_type:
      type: string
      title: check_type
      enum:
        - driver_license_status
        - motor_vehicle_report
    driver-check-request-from-pii:
      type: object
      properties:
        first_name:
          type: string
          description: First name of the person
        last_name:
          type: string
          description: Last name of the person
        dob:
          $ref: '#/components/schemas/date'
          description: >
            Date of birth (ISO 8601 date string).

            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`.
        driver_license_number:
          type: string
          description: Driver license number
        driver_license_state:
          $ref: '#/components/schemas/state_code'
          description: State that issued the driver license
        check_type:
          $ref: '#/components/schemas/driver_check_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      required:
        - first_name
        - last_name
        - driver_license_number
        - driver_license_state
        - check_type
    driver-check-request-from-profile:
      type: object
      properties:
        profile_id:
          $ref: '#/components/schemas/profile_id'
        check_type:
          $ref: '#/components/schemas/driver_check_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      required:
        - profile_id
        - check_type
    driver_check:
      oneOf:
        - $ref: '#/components/schemas/driver_check_driver_license_status'
        - $ref: '#/components/schemas/driver_check_motor_vehicle_report'
    driver-license-status-completed-event-body:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        object:
          type: string
          enum:
            - event
        type:
          type: string
          enum:
            - driver_license_status.completed
        created_at:
          $ref: '#/components/schemas/datetime'
        data:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/uuid'
            created_at:
              $ref: '#/components/schemas/datetime'
            completed_at:
              $ref: '#/components/schemas/datetime'
            results:
              $ref: '#/components/schemas/driver_check_driver_license_status_result'
            profile:
              $ref: '#/components/schemas/profile'
            check_type:
              $ref: '#/components/schemas/check_type_driver_license_status'
            reference_id:
              $ref: '#/components/schemas/reference_id'
        account_id:
          $ref: '#/components/schemas/uuid'
      required:
        - id
        - object
        - type
        - created_at
        - data
        - account_id
    motor-vehicle-report-completed-event-body:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        object:
          type: string
          enum:
            - event
        type:
          type: string
          enum:
            - motor_vehicle_report.completed
        created_at:
          $ref: '#/components/schemas/datetime'
        data:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/uuid'
            created_at:
              $ref: '#/components/schemas/datetime'
            completed_at:
              $ref: '#/components/schemas/datetime'
            results:
              $ref: '#/components/schemas/driver_check_motor_vehicle_report_result'
            profile:
              $ref: '#/components/schemas/profile'
            check_type:
              $ref: '#/components/schemas/check_type_motor_vehicle_report'
            reference_id:
              $ref: '#/components/schemas/reference_id'
        account_id:
          $ref: '#/components/schemas/uuid'
      required:
        - id
        - object
        - type
        - created_at
        - data
        - account_id
    attribute_match_score:
      description: 0 if an attribute does not match, 100 if it matches
      type: integer
      enum:
        - 0
        - 100
    attribute_match_scores:
      description: attribute match scores
      type: object
      properties:
        first_name:
          $ref: '#/components/schemas/attribute_match_score'
        last_name:
          $ref: '#/components/schemas/attribute_match_score'
        dob:
          $ref: '#/components/schemas/attribute_match_score'
        phone:
          $ref: '#/components/schemas/attribute_match_score'
        email:
          $ref: '#/components/schemas/attribute_match_score'
        address:
          $ref: '#/components/schemas/attribute_match_score'
        city:
          $ref: '#/components/schemas/attribute_match_score'
        state:
          $ref: '#/components/schemas/attribute_match_score'
        zip_code:
          $ref: '#/components/schemas/attribute_match_score'
        ssn:
          $ref: '#/components/schemas/attribute_match_score'
      example:
        first_name: 100
        last_name: 100
        dob: 100
        phone: 100
        email: 0
        address: 100
        city: 100
        state: 100
        zip_code: 100
        ssn: 0
    attribute_match_score_overall:
      description: >-
        0 if no attributes match, 50 if some attributes match, 100 if all
        attributes match
      type: integer
      enum:
        - 0
        - 50
        - 100
      example: 50
    idv_result_context_item:
      title: idv_result_context_item
      type: object
      properties:
        code:
          type: string
          description: A stable code for the reason or context
          example: CT-0195
        title:
          type: string
          description: A user-friendly description of the reason or context
          example: Address is correlated with a past address
        category:
          type: string
          description: Category derived from the provider reason code.
          enum:
            - informational
            - rejection
            - unknown
          example: informational
    idv_result_pii_validation:
      title: idv_result_pii_validation
      type: object
      properties:
        attribute_match_scores:
          $ref: '#/components/schemas/attribute_match_scores'
        overall_match_score:
          $ref: '#/components/schemas/attribute_match_score_overall'
        result_context:
          type: array
          items:
            $ref: '#/components/schemas/idv_result_context_item'
    idv_collection_link:
      title: idv_collection_link
      type: object
      properties:
        url:
          description: URL for the document collection application.
          type: string
          format: uri
        qr_code:
          description: Base64 encoded PNG image of a QR code linking to the collection URL.
          type: string
          format: byte
    idv_document_type:
      title: idv_document_type
      type: object
      properties:
        type:
          description: The type of document identified (e.g., Drivers License, Passport).
          type: string
          example: Drivers License
        country:
          description: The country of issuance.
          type: string
          example: USA
        state:
          description: The state/province of issuance (if applicable).
          type: string
          example: CO
    idv_document_data:
      title: idv_document_data
      type: object
      properties:
        first_name:
          description: First name extracted from the document.
          type: string
          example: Dwayne
        sur_name:
          description: Last name extracted from the document.
          type: string
          example: Denver
        full_name:
          description: Full name extracted from the document.
          type: string
          example: Dwayne Denver
        address:
          description: Address extracted from the document.
          type: string
          example: 123 Example Street, New York City, NY 10001
        parsed_address:
          description: Address components parsed from the extracted address.
          type: object
          properties:
            physical_address:
              description: The primary address line of the address.
              type: string
            physical_address2:
              description: The secondary address line of the address.
              type: string
            city:
              description: The city of the address.
              type: string
            state:
              description: The state of the address.
              type: string
            country:
              description: The country of the address.
              type: string
            zip:
              description: The ZIP code of the address.
              type: string
        document_number:
          description: Document identification number.
          type: string
          example: '000000000'
        dob:
          description: Date of birth extracted from the document.
          type: string
          format: date
          example: '1990-01-01'
        issue_date:
          description: Date the document was issued.
          type: string
          format: date
          example: '2020-01-01'
        expiration_date:
          description: Date the document expires.
          type: string
          format: date
          example: '2027-01-01'
    idv_result_document_verification:
      title: idv_result_document_verification
      type: object
      properties:
        status:
          description: The current status of the document verification process.
          type: string
          enum:
            - started
            - documents_collected
            - complete
        result:
          description: The final result of the verification, or null if not complete.
          type: string
          enum:
            - accept
            - reject
            - resubmit
            - failed
        errors:
          description: >-
            List of error codes if the process failed or encountered issues
            (e.g., consent_declined, session_expired).
          $ref: '#/components/schemas/errors'
        collection_link:
          description: Link details for the document collection step.
          $ref: '#/components/schemas/idv_collection_link'
        result_context:
          description: >-
            Array of objects describing reasons or context associated with the
            result.
          type: array
          items:
            $ref: '#/components/schemas/idv_result_context_item'
          example:
            - code: CT-0167
              title: First name extracted from document correlates with input name
              category: informational
            - code: CT-0171
              title: >-
                Document number extracted from document correlates with input
                number
              category: informational
        document_type:
          description: Details about the type of document submitted.
          $ref: '#/components/schemas/idv_document_type'
        document_data:
          description: Data extracted from the submitted document.
          $ref: '#/components/schemas/idv_document_data'
      example:
        status: complete
        result: accept
        errors: []
        collection_link:
          url: https://example.com
          qr_code: ''
        result_context:
          - code: CT-0167
            title: First name extracted from document correlates with input name
            category: informational
          - code: CT-0171
            title: >-
              Document number extracted from document correlates with input
              number
            category: informational
        document_type:
          type: Drivers License
          country: USA
          state: CO
        document_data:
          first_name: Dwayne
          sur_name: Denver
          full_name: Dwayne Denver
          address: 123 Example Street, New York City, NY 10001
          parsed_address:
            physical_address: 123 Example Street
            physical_address2: Suite 200
            city: New York City
            state: NY
            zip: '10001'
            country: USA
          document_number: '000000000'
          dob: '2000-01-01'
          issue_date: '2020-01-01'
          expiration_date: '2027-01-01'
    idv_result_personal_identity_records:
      title: idv_result_personal_identity_records
      type: object
      properties:
        request:
          description: The request parameters used for the search
          type: object
          properties:
            first_name:
              description: The first name of the person
              type: string
            middle_name:
              description: The middle name of the person
              type: string
            last_name:
              description: The last name of the person
              type: string
            dob:
              $ref: '#/components/schemas/date_string_complete'
            phone:
              $ref: '#/components/schemas/phone_string'
            email:
              $ref: '#/components/schemas/email_string'
            ssn:
              $ref: '#/components/schemas/ssn_string'
            address:
              $ref: '#/components/schemas/address'
            reference_id:
              $ref: '#/components/schemas/reference_id'
        people:
          description: Array of identity records found matching the search criteria
          type: array
          items:
            type: object
            properties:
              name:
                description: The person's name components
                type: object
                properties:
                  first_name:
                    type: string
                  middle_name:
                    type: string
                  last_name:
                    type: string
                  full_name:
                    type: string
              dobs:
                description: >-
                  Array of dates of birth associated with this identity (format
                  YYYYMMDD, with 00 for unknown components)
                type: array
                items:
                  type: string
                  pattern: ^[0-9]{8}$
                  example: '19900115'
              phones:
                description: Array of phone numbers associated with this identity
                type: array
                items:
                  type: string
              ssn:
                description: >-
                  Social security number. Please note that this is not enabled
                  by default - if you need it for your use case, please reach
                  out to your Checkr Trust Account Executive or Customer Success
                  representative.
                type: string
              addresses:
                description: Array of addresses associated with this identity
                type: array
                items:
                  type: object
                  properties:
                    street:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    zip_code:
                      type: string
                    county:
                      type: string
                      description: County name
                    country:
                      type: string
                    from_date:
                      type: string
                      format: date
                      description: First date the person was associated with this address
                    to_date:
                      type: string
                      format: date
                      description: Last date the person was associated with this address
              aliases:
                description: Array of name aliases associated with this identity
                type: array
                items:
                  type: object
                  properties:
                    first_name:
                      type: string
                    middle_name:
                      type: string
                    last_name:
                      type: string
                    full_name:
                      type: string
      example:
        request:
          first_name: JOHN
          last_name: SMITH
          dob: '19900115'
        people:
          - name:
              first_name: JOHN
              middle_name: ALLEN
              last_name: SMITH
              full_name: JOHN ALLEN SMITH
            dobs:
              - '19900115'
            phones:
              - '+15551234567'
            ssn: '***-**-1234'
            addresses:
              - street: 123 MAIN ST
                city: ANYTOWN
                state: CA
                zip_code: '12345'
                county: LINCOLN
                country: US
                from_date: '2018-03-15'
                to_date: '2024-01-20'
            aliases:
              - first_name: JOHNNY
                last_name: SMITH
    idv_type:
      description: The type of identity verification to be done.
      type: string
      title: idv_type
      enum:
        - pii_validation
        - document_verification
        - personal_identity_records
      x-enumDescriptions:
        pii_validation: >-
          When requesting pii_validation, the result will be returned
          immediately.
        document_verification: >-
          When requesting document_verification, the result will be returned
          asynchronously through a pre-defined webhook.
        personal_identity_records: >-
          When requesting personal_identity_records, enriched identity
          information will be returned immediately.
      default: pii_validation
    identity_verification:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          $ref: '#/components/schemas/datetime'
        results:
          description: The structure of results depends on the value of idv_type.
          oneOf:
            - $ref: '#/components/schemas/idv_result_pii_validation'
            - $ref: '#/components/schemas/idv_result_document_verification'
            - $ref: '#/components/schemas/idv_result_personal_identity_records'
        idv_type:
          $ref: '#/components/schemas/idv_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
          title: identity verification with profile id
          required:
            - profile_id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
          title: identity verification with profile object
          required:
            - profile
    identity-verification-request-from-pii:
      description: the request to create a new identity verification from set of PII
      type: object
      properties:
        idv_type:
          $ref: '#/components/schemas/idv_type'
        first_name:
          description: The first name of the person
          type: string
        middle_name:
          description: For document verification, the middle name of the person.
          type: string
        last_name:
          description: The last name of the person
          type: string
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        phone:
          $ref: '#/components/schemas/phone_string'
        email:
          $ref: '#/components/schemas/email_string'
        ssn:
          $ref: '#/components/schemas/ssn_string'
        address:
          $ref: '#/components/schemas/address'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        send_message:
          description: >
            For document verification, whether the end user should receive an
            SMS with the collection link to the provided phone number.

            Defaults to false if not provided.
          type: boolean
          default: false
        skip_selfie:
          description: >-
            For document verification, whether we should skip collecting and
            verifying a selfie. Defaults to false.
          type: boolean
          default: false
      required:
        - first_name
        - last_name
        - idv_type
      anyOf:
        - title: dob-is-required
          description: The object must have DOB.
          required:
            - dob
        - title: phone-is-required
          description: The object must have phone number.
          required:
            - phone
        - title: email-is-required
          description: The object must have email.
          required:
            - email
        - title: address-is-required
          description: The object must have address.
          required:
            - address
        - title: ssn-is-required
          description: The object must have an SSN.
          required:
            - ssn
      example:
        first_name: JOHN
        last_name: SMITH
        idv_type: pii_validation
        email: j.doe@example.com
    identity-verification-request-from-profile:
      description: >-
        the request to create a new identity verification from an existing
        profile
      properties:
        idv_type:
          $ref: '#/components/schemas/idv_type'
        profile_id:
          $ref: '#/components/schemas/profile_id'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        send_message:
          description: >-
            For document verification, whether the end user should receive an
            SMS with the collection link to the provided phone number. Defaults
            to false if not provided.
          type: boolean
        skip_selfie:
          description: >-
            For document verification, whether we should skip collecting and
            verifying a selfie. Defaults to false.
          type: boolean
          default: false
      required:
        - profile_id
        - idv_type
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
        idv_type: pii_validation
    idv_result_document_verification_initial:
      title: idv_result_document_verification_initial
      type: object
      properties:
        status:
          type: string
          enum:
            - started
          description: The initial status of the document verification process.
        collection_link:
          $ref: '#/components/schemas/idv_collection_link'
          description: Link details for the document collection step.
      required:
        - status
        - collection_link
    identity_verification_post_response:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: the UUID of the identity verification.
        created_at:
          $ref: '#/components/schemas/datetime'
        results:
          description: The structure of results depends on the value of idv_type.
          oneOf:
            - $ref: '#/components/schemas/idv_result_pii_validation'
            - $ref: '#/components/schemas/idv_result_document_verification_initial'
            - $ref: '#/components/schemas/idv_result_personal_identity_records'
        profile_id:
          $ref: '#/components/schemas/uuid'
          description: the UUID of the profile.
        profile:
          $ref: '#/components/schemas/profile'
        idv_type:
          $ref: '#/components/schemas/idv_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
      required:
        - id
        - created_at
        - results
        - idv_type
    document-verification-completed-event-body:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        object:
          type: string
          enum:
            - event
        type:
          type: string
          enum:
            - document_verification.completed
        created_at:
          $ref: '#/components/schemas/datetime'
        data:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/uuid'
            created_at:
              $ref: '#/components/schemas/datetime'
            completed_at:
              $ref: '#/components/schemas/datetime'
            results:
              oneOf:
                - $ref: '#/components/schemas/idv_result_document_verification'
              description: The structure of results depends on the value of idv_type.
            profile_id:
              type: string
              format: uuid
            idv_type:
              type: string
              enum:
                - document_verification
            reference_id:
              $ref: '#/components/schemas/reference_id'
        account_id:
          $ref: '#/components/schemas/uuid'
      required:
        - id
        - object
        - type
        - created_at
        - data
        - account_id
    profile_request_from_pii:
      description: >
        The request to create a new profile from a set of personally
        identifiable information (PII).

        At least one of the following must be provided in addition to first and
        last name - DOB, phone, email, address, or SSN.

        The more identity fields provided (SSN, email, phone), the better the
        matching and verification capabilities will be.

        These fields are used for additional identity verification and record
        matching in various check products.
      type: object
      properties:
        first_name:
          description: The first name of the person.
          type: string
        middle_name:
          description: The middle name of the person. Can be null if not provided.
          type: string
        last_name:
          description: The last name of the person.
          type: string
        dob:
          $ref: '#/components/schemas/date_string_complete'
        phone:
          description: >-
            A phone number in the form +[country code][number including area
            code]. (E.164 format)
          $ref: '#/components/schemas/phone_string'
        email:
          $ref: '#/components/schemas/email_string'
        ssn:
          $ref: '#/components/schemas/ssn_string'
        address:
          $ref: '#/components/schemas/address'
        custom_id:
          $ref: '#/components/schemas/custom_id_string'
      required:
        - first_name
        - last_name
      anyOf:
        - title: dob-is-required
          description: The object must have DOB.
          required:
            - dob
        - title: phone-is-required
          description: The object must have phone number.
          required:
            - phone
        - title: email-is-required
          description: The object must have email.
          required:
            - email
        - title: address-is-required
          description: The object must have address.
          required:
            - address
        - title: ssn-is-required
          description: The object must have an SSN.
          required:
            - ssn
      example:
        first_name: JOHN
        middle_name: ROBERT
        last_name: SMITH
        dob: '19900101'
        ssn: 123-45-6789
        email: john.smith@example.com
        phone: '+14155552671'
        address:
          street: 123 Main St
          city: San Francisco
          state: CA
          zip_code: '94105'
        custom_id: employee-123
    profile_request_from_address:
      description: >-
        The request to create a new profile from an address only. This is used
        when you only have address information and no personal identifiers.
      type: object
      properties:
        address:
          $ref: '#/components/schemas/address'
        custom_id:
          $ref: '#/components/schemas/custom_id_string'
      required:
        - address
      example:
        address:
          street: 123 Example Street
          city: New York City
          state: NY
          zip_code: '10001'
          country: US
    profile_request_from_profile:
      description: >-
        The request to create a new profile by copying an existing profile's
        information. This allows reusing previously validated profile data.
      type: object
      properties:
        profile_id:
          $ref: '#/components/schemas/profile_id'
        custom_id:
          $ref: '#/components/schemas/custom_id_string'
      required:
        - profile_id
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
    legal_check:
      type: object
      description: |
        A legal annotation check result indicating how a record, case, or charge
        was evaluated against applicable legal rules.
      properties:
        action_type:
          type: string
          description: >
            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
          example: note
        rule_id:
          type: string
          description: Identifier of the legal rule that triggered this check result.
          example: CA-7yr-felony
        rule_type:
          type: string
          description: |
            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
          example: legal
        domain:
          type: string
          description: The filter domain in which this rule was applied.
          example: employment
        description:
          type: string
          description: Human-readable description of what the legal rule evaluated.
          example: >-
            Felony convictions older than 7 years cannot be reported in
            California
        run_at:
          type: string
          format: date-time
          description: The timestamp when this check was evaluated.
          example: '2024-01-15T10:30:00.000Z'
    regulated_charge:
      description: A charge with legal annotation checks.
      allOf:
        - $ref: '#/components/schemas/charge'
        - type: object
          properties:
            checks:
              type: array
              description: Legal annotation check results for this charge.
              items:
                $ref: '#/components/schemas/legal_check'
    regulated_case:
      description: A case with legal annotation checks.
      allOf:
        - $ref: '#/components/schemas/case'
        - type: object
          properties:
            charges:
              description: Charges in this case, with legal annotation checks.
              type: array
              items:
                $ref: '#/components/schemas/regulated_charge'
            checks:
              type: array
              description: Legal annotation check results for this case.
              items:
                $ref: '#/components/schemas/legal_check'
    regulated_record:
      title: regulated_record
      description: >-
        A criminal record with legal annotation checks at record, case, and
        charge levels.
      allOf:
        - $ref: '#/components/schemas/record'
        - type: object
          properties:
            cases:
              description: Cases in this record, with legal annotation checks.
              type: array
              items:
                $ref: '#/components/schemas/regulated_case'
            checks:
              type: array
              description: Legal annotation check results for this record.
              items:
                $ref: '#/components/schemas/legal_check'
    regulated_check_type:
      type: string
      description: >-
        The type of regulated check. Currently only instant_criminal_regulated
        is supported.
      enum:
        - instant_criminal_regulated
      default: instant_criminal_regulated
    regulated_check:
      type: object
      description: >-
        A regulated check response with legal annotation checks included in
        results.
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          $ref: '#/components/schemas/datetime'
        results:
          description: When there are no results found, this will be an empty array.
          type: array
          items:
            $ref: '#/components/schemas/regulated_record'
        check_type:
          $ref: '#/components/schemas/regulated_check_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        run_notes:
          description: >
            An unstructured array of human-readable notes about this particular
            check.

            May contain notes about how input was parsed or other information
            about results.
          type: array
          items:
            type: string
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
          title: regulated check with profile id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
          title: regulated check with profile object
    jurisdiction:
      type: object
      description: >-
        A geographic jurisdiction specified by state, and optionally county and
        city.
      properties:
        state:
          $ref: '#/components/schemas/state_code'
        county:
          type: string
          description: The county name within the state.
          example: Los Angeles
        city:
          type: string
          description: The city name within the jurisdiction.
          example: San Francisco
    filter_context:
      type: object
      description: >
        Context information used to determine which legal rules apply when
        filtering check results.

        Jurisdictions help identify applicable state and local regulations that
        may affect

        which records can be reported.
      properties:
        candidate_jurisdiction:
          description: >-
            The jurisdiction where the candidate (subject of the check) is
            located.
          $ref: '#/components/schemas/jurisdiction'
        decider_jurisdiction:
          description: >-
            The jurisdiction where the decision-maker (employer/requester) is
            located.
          $ref: '#/components/schemas/jurisdiction'
        property_jurisdiction:
          description: >-
            The jurisdiction of the property involved (for tenancy-related
            checks).
          $ref: '#/components/schemas/jurisdiction'
      required:
        - candidate_jurisdiction
    permissible_purpose:
      type: string
      description: >
        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 checks to ensure compliance with
        federal regulations.
      enum:
        - Court Order
        - Consumer Instruction
        - Credit Transaction
        - Employment
        - Insurance Underwriting
        - Benefit Eligibility
        - Credit Risk
        - Consumer Initiated
        - Account Review
        - Govt Chargecard
        - Child Support
        - Agency Liquidation
      example: Employment
    regulated_check_request_from_pii:
      type: object
      description: >-
        Request to create a regulated check using personally identifiable
        information (PII).
      properties:
        check_type:
          $ref: '#/components/schemas/regulated_check_type'
        first_name:
          description: First name (given name). Do not include prefixes like "Ms." or "Dr."
          type: string
          example: Jane
        middle_name:
          description: Middle name(s)
          type: string
          example: Mary Louise
        last_name:
          description: Last name (surname). Do not include suffixes like "Jr." or "2nd".
          type: string
          example: Smith
        full_name:
          description: >
            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.
          type: string
          example: Smith, Jane Mary Louise
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        ssn:
          description: >-
            Social Security Number used for additional identity verification and
            record matching
          $ref: '#/components/schemas/ssn_string'
        phone:
          $ref: '#/components/schemas/phone_string'
        addresses:
          description: An array of addresses to search for criminal records.
          type: array
          items:
            $ref: '#/components/schemas/address_request'
        filter_context:
          $ref: '#/components/schemas/filter_context'
        permissible_purpose:
          $ref: '#/components/schemas/permissible_purpose'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
      required:
        - first_name
        - last_name
        - dob
        - filter_context
        - permissible_purpose
      example:
        first_name: JOHN
        last_name: SMITH
        dob: '19900101'
        ssn: 123-45-6789
        phone: '+14155552671'
        addresses:
          - street: 456 Oak Ave
            city: Los Angeles
            state: CA
            zip_code: '90001'
        filter_context:
          candidate_jurisdiction:
            state: CA
          decider_jurisdiction:
            state: NY
        permissible_purpose: Employment
    regulated_check_request_from_profile:
      description: Request to create a regulated check from an existing profile.
      type: object
      properties:
        check_type:
          $ref: '#/components/schemas/regulated_check_type'
        profile_id:
          $ref: '#/components/schemas/profile_id'
        filter_context:
          $ref: '#/components/schemas/filter_context'
        permissible_purpose:
          $ref: '#/components/schemas/permissible_purpose'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
      required:
        - profile_id
        - filter_context
        - permissible_purpose
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
        filter_context:
          candidate_jurisdiction:
            state: CA
          decider_jurisdiction:
            state: NY
        permissible_purpose: Employment
    criminal_report_check_type:
      type: string
      description: The type of check performed for this report.
      enum:
        - instant_criminal_regulated
      default: instant_criminal_regulated
    regulated_criminal_report:
      type: object
      description: >
        A regulated criminal report with legal annotation checks included in
        results.

        Results are delivered asynchronously via webhook once processing is
        complete.
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        status:
          type: string
          description: The current status of the report.
          enum:
            - pending
            - complete
            - failed
          example: complete
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          $ref: '#/components/schemas/datetime'
        results:
          description: When there are no results found, this will be an empty array.
          type: array
          items:
            $ref: '#/components/schemas/regulated_record'
        check_type:
          $ref: '#/components/schemas/criminal_report_check_type'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        run_notes:
          description: >
            An unstructured array of human-readable notes about this particular
            report.

            May contain notes about how input was parsed or other information
            about results.
          type: array
          items:
            type: string
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
          title: regulated criminal report with profile id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
          title: regulated criminal report with profile object
    schemas_filter_context:
      type: object
      description: >
        Context information used to determine which legal rules apply when
        filtering report results.

        Jurisdictions help identify applicable state and local regulations that
        may affect

        which records can be reported.
      properties:
        candidate_jurisdiction:
          description: >-
            The jurisdiction where the candidate (subject of the report) is
            located.
          $ref: '#/components/schemas/jurisdiction'
        decider_jurisdiction:
          description: >-
            The jurisdiction where the decision-maker (employer/requester) is
            located.
          $ref: '#/components/schemas/jurisdiction'
        property_jurisdiction:
          description: >-
            The jurisdiction of the property involved (for tenancy-related
            reports).
          $ref: '#/components/schemas/jurisdiction'
      required:
        - candidate_jurisdiction
    schemas_permissible_purpose:
      type: string
      description: >
        The permissible purpose for requesting this criminal record report, as
        required by the Fair Credit Reporting Act (FCRA).

        This must be provided for all regulated criminal reports to ensure
        compliance with federal regulations.
      enum:
        - Court Order
        - Consumer Instruction
        - Credit Transaction
        - Employment
        - Insurance Underwriting
        - Benefit Eligibility
        - Credit Risk
        - Consumer Initiated
        - Account Review
        - Govt Chargecard
        - Child Support
        - Agency Liquidation
      example: Employment
    criminal_report_request_from_pii:
      type: object
      description: >-
        Request to create a regulated criminal report using personally
        identifiable information (PII).
      properties:
        check_type:
          $ref: '#/components/schemas/criminal_report_check_type'
        first_name:
          description: First name (given name). Do not include prefixes like "Ms." or "Dr."
          type: string
          example: Jane
        middle_name:
          description: Middle name(s)
          type: string
          example: Mary Louise
        last_name:
          description: Last name (surname). Do not include suffixes like "Jr." or "2nd".
          type: string
          example: Smith
        full_name:
          description: >
            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.
          type: string
          example: Smith, Jane Mary Louise
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        ssn:
          description: >-
            Social Security Number used for additional identity verification and
            record matching
          $ref: '#/components/schemas/ssn_string'
        phone:
          $ref: '#/components/schemas/phone_string'
        addresses:
          description: An array of addresses to search for criminal records.
          type: array
          items:
            $ref: '#/components/schemas/address_request'
        filter_context:
          $ref: '#/components/schemas/schemas_filter_context'
        permissible_purpose:
          $ref: '#/components/schemas/schemas_permissible_purpose'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
      required:
        - first_name
        - last_name
        - dob
        - filter_context
        - permissible_purpose
      example:
        first_name: JOHN
        last_name: SMITH
        dob: '19900101'
        ssn: 123-45-6789
        phone: '+14155552671'
        addresses:
          - street: 456 Oak Ave
            city: Los Angeles
            state: CA
            zip_code: '90001'
        filter_context:
          candidate_jurisdiction:
            state: CA
          decider_jurisdiction:
            state: NY
        permissible_purpose: Employment
    criminal_report_request_from_profile:
      description: Request to create a regulated criminal report from an existing profile.
      type: object
      properties:
        check_type:
          $ref: '#/components/schemas/criminal_report_check_type'
        profile_id:
          $ref: '#/components/schemas/profile_id'
        filter_context:
          $ref: '#/components/schemas/schemas_filter_context'
        permissible_purpose:
          $ref: '#/components/schemas/schemas_permissible_purpose'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
      required:
        - profile_id
        - filter_context
        - permissible_purpose
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
        filter_context:
          candidate_jurisdiction:
            state: CA
          decider_jurisdiction:
            state: NY
        permissible_purpose: Employment
    regulated_criminal_report_created:
      type: object
      description: >-
        Response returned when a regulated criminal report is created. Full
        results are delivered asynchronously via webhook.
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        status:
          type: string
          description: The current status of the report.
          enum:
            - pending
            - complete
            - failed
          example: pending
    county_check_request_from_pii:
      description: >-
        Request to create a county check using personally identifiable
        information (PII).
      type: object
      properties:
        first_name:
          description: First name of the person. Required when not using profile_id.
          type: string
          example: Jane
        middle_name:
          description: Middle name of the person.
          type: string
          example: Mary
        last_name:
          description: Last name of the person. Required when not using profile_id.
          type: string
          example: Smith
        dob:
          description: |
            Date of birth in the form YYYYMMDD.
            Must be a valid date and cannot be in the future.
            Required when not using profile_id.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        state:
          description: The two-letter US state code where the county is located.
          $ref: '#/components/schemas/state_code'
        county_fips_code:
          description: |
            The 5-digit FIPS code for the county to search.
            FIPS codes are standardized geographic identifiers assigned by the
            Federal Information Processing Standards.
          type: string
          pattern: ^\d{5}$
          example: '06075'
        lookback_period_in_years:
          description: >
            Optional number of years to look back for criminal records.

            If not provided, the default lookback period configured for the
            account will be used.
          type: integer
          minimum: 1
          maximum: 100
          example: 7
        include_null_date_of_birth:
          description: >
            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).
          type: boolean
          example: true
        reference_id:
          $ref: '#/components/schemas/reference_id'
      required:
        - first_name
        - last_name
        - dob
        - state
        - county_fips_code
      example:
        first_name: Jane
        middle_name: Mary
        last_name: Smith
        dob: '19900115'
        state: CA
        county_fips_code: '06075'
        lookback_period_in_years: 7
    county_check_request_from_profile:
      description: Request to create a county check from an existing profile.
      type: object
      properties:
        profile_id:
          description: The unique identifier of an existing profile containing PII.
          $ref: '#/components/schemas/profile_id'
        state:
          description: The two-letter US state code where the county is located.
          $ref: '#/components/schemas/state_code'
        county_fips_code:
          description: |
            The 5-digit FIPS code for the county to search.
            FIPS codes are standardized geographic identifiers assigned by the
            Federal Information Processing Standards.
          type: string
          pattern: ^\d{5}$
          example: '06075'
        lookback_period_in_years:
          description: >
            Optional number of years to look back for criminal records.

            If not provided, the default lookback period configured for the
            account will be used.
          type: integer
          minimum: 1
          maximum: 100
          example: 7
        include_null_date_of_birth:
          description: >
            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).
          type: boolean
          example: true
        reference_id:
          $ref: '#/components/schemas/reference_id'
      required:
        - profile_id
        - state
        - county_fips_code
      example:
        profile_id: 2b8313e8-4efd-45a1-b578-952b8313e890
        state: CA
        county_fips_code: '06075'
        lookback_period_in_years: 7
    county_check_request:
      description: >-
        Request to create a county check, either from PII or from an existing
        profile.
      oneOf:
        - $ref: '#/components/schemas/county_check_request_from_pii'
        - $ref: '#/components/schemas/county_check_request_from_profile'
    county_check_type:
      description: The type of county check.
      type: string
      title: county_check_type
      enum:
        - county_criminal
      default: county_criminal
    county_check_status:
      description: The current status of the county check.
      type: string
      title: county_check_status
      enum:
        - pending
        - completed
        - cancelled
      example: pending
    county_check_search_criteria:
      description: The search criteria used for the county check.
      type: object
      properties:
        first_name:
          description: First name of the person.
          type: string
          example: Jane
        middle_name:
          description: Middle name of the person.
          type: string
          example: Mary
        last_name:
          description: Last name of the person.
          type: string
          example: Smith
        dob:
          description: Date of birth in the form YYYYMMDD.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        state:
          description: The two-letter US state code.
          $ref: '#/components/schemas/state_code'
        county_fips_code:
          description: The FIPS code for the county.
          type: string
          pattern: ^\d{5}$
          example: '06075'
        lookback_period_in_years:
          description: The number of years to look back for criminal records.
          type: integer
          example: 7
    county_check:
      type: object
      description: A county criminal check response.
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        created_at:
          $ref: '#/components/schemas/datetime'
        completed_at:
          description: The timestamp when the check was completed. Null if still pending.
          oneOf:
            - $ref: '#/components/schemas/datetime'
            - type: 'null'
        check_type:
          $ref: '#/components/schemas/county_check_type'
        status:
          $ref: '#/components/schemas/county_check_status'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        search_criteria:
          $ref: '#/components/schemas/county_check_search_criteria'
        results:
          description: |
            The results of the county check.
            Empty array if no records found or if the check is still pending.
          type: array
          items:
            $ref: '#/components/schemas/record'
      oneOf:
        - properties:
            profile_id:
              $ref: '#/components/schemas/profile_id'
          title: county check with profile id
        - properties:
            profile:
              $ref: '#/components/schemas/profile'
          title: county check with profile object
    county_check_cancel_request:
      description: Request to cancel a pending county check.
      type: object
      properties:
        reason:
          description: The reason for cancelling the county check.
          type: string
          minLength: 1
          maxLength: 500
          example: Candidate withdrew application
      required:
        - reason
      example:
        reason: Candidate withdrew application
    criminal_check:
      description: >
        A criminal check result. Results are only available after webhook
        delivery (completed_at is set).

        Before webhook delivery, the results array will be empty.
      allOf:
        - $ref: '#/components/schemas/check'
        - type: object
          properties:
            completed_at:
              description: >-
                Timestamp when the check was completed and webhook was
                delivered.
              type: string
              format: date-time
    criminal-check-request-from-pii:
      description: |
        Request to create a new criminal check using PII.
      type: object
      properties:
        input_type:
          $ref: '#/components/schemas/input_type'
        first_name:
          description: >-
            first name (given name).  Do not include prefixes, like "Ms." or
            "Dr."
          type: string
          example: Jane
        middle_name:
          description: middle name(s)
          type: string
          example: Mary Louise
        last_name:
          description: last name (surname).  Do not include suffixes, like "Jr." or "2nd".
          type: string
          example: O'Donnell-Van Helsing
        full_name:
          description: >
            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,

            and then use those for the check.

            If you already know the first and last names, we suggest sending
            them.

            The parser will attempt to remove prefixes and suffixes, and handles
            several different formats of name,

            but we cannot guarantee it will parse the name in the manner you
            expect.
          type: string
          example: O'Donnell-Van Helsing, Dr. Jane Mary Louise, MD
        dob:
          description: >
            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`.
          allOf:
            - $ref: '#/components/schemas/date_string_complete'
        ssn:
          description: >-
            Social Security Number used for additional identity verification and
            record matching
          $ref: '#/components/schemas/ssn_string'
        phone:
          $ref: '#/components/schemas/phone_string'
        addresses:
          description: >
            An array of addresses to search for criminal records.

            When provided, records will be matched against any of the addresses
            in the array.
          type: array
          items:
            $ref: '#/components/schemas/address_request'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
        order_by:
          $ref: '#/components/schemas/order_by'
      required:
        - first_name
        - last_name
      example:
        first_name: JOHN
        last_name: SMITH
        dob: '19900101'
        ssn: 123-45-6789
        phone: '+14155552671'
        addresses:
          - street: 456 Oak Ave
            city: Los Angeles
            state: CA
            zip_code: '90001'
    criminal-check-request-from-profile:
      description: >
        Request to create a new criminal check from an existing profile.

        Note: check_type is automatically set to 'criminal_check' and cannot be
        specified.
      type: object
      properties:
        profile_id:
          $ref: '#/components/schemas/profile_id'
        input_type:
          $ref: '#/components/schemas/input_type'
        ruleset_id:
          $ref: '#/components/schemas/ruleset_id'
        ruleset_ids:
          $ref: '#/components/schemas/ruleset_ids'
        reference_id:
          $ref: '#/components/schemas/reference_id'
        source_states:
          $ref: '#/components/schemas/source_states'
        order_by:
          $ref: '#/components/schemas/order_by'
      required:
        - profile_id
      example:
        profile_id: 014f2478-fc46-46d3-9f1a-b9641e1aa080
    criminal-check-completed-event-body:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        object:
          type: string
          enum:
            - event
        type:
          type: string
          enum:
            - criminal_check.completed
        created_at:
          $ref: '#/components/schemas/datetime'
        data:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/uuid'
            created_at:
              $ref: '#/components/schemas/datetime'
            completed_at:
              $ref: '#/components/schemas/datetime'
            results:
              description: When there are no results found, this will be an empty array.
              type: array
              items:
                $ref: '#/components/schemas/record'
            profile:
              $ref: '#/components/schemas/profile'
            check_type:
              type: string
              enum:
                - criminal_check
            input_type:
              $ref: '#/components/schemas/input_type'
            reference_id:
              $ref: '#/components/schemas/reference_id'
        account_id:
          $ref: '#/components/schemas/uuid'
      required:
        - id
        - object
        - type
        - created_at
        - data
        - account_id
  responses:
    post-token-response-body:
      description: OK - success response from create token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/token'
    post-token-unauthorized-response-body:
      description: Unauthorized - not allowed to response from create token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    rate-limit-exceeded:
      description: >
        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).
      headers:
        X-RateLimit-Limit:
          description: Maximum number of API calls allowed for this product configuration.
          schema:
            type: string
            example: '100'
        X-RateLimit-Remaining:
          description: Number of calls remaining in the current limit period.
          schema:
            type: string
            example: '0'
        X-RateLimit-Expires:
          description: >-
            ISO 8601 timestamp after which product access expires (present only
            when access_expires_at is set).
          schema:
            type:
              - string
              - 'null'
            format: date-time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
  requestBodies:
    post-profile-request-body:
      description: The request body for creating a new profile
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/profile_request_from_pii'
              - $ref: '#/components/schemas/profile_request_from_address'
              - $ref: '#/components/schemas/profile_request_from_profile'
    post-check-request-body:
      description: The request body for creating a new check
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/check-request-from-pii'
              - $ref: '#/components/schemas/check-request-from-address'
              - $ref: '#/components/schemas/check-request-from-profile'
    post-regulated-check-request-body:
      description: >-
        The request body for creating a new regulated check with legal
        annotation
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/regulated_check_request_from_pii'
              - $ref: '#/components/schemas/regulated_check_request_from_profile'
    post-identity-verification-request-body:
      description: The request body for creating a new identity verification
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/identity-verification-request-from-pii'
              - $ref: >-
                  #/components/schemas/identity-verification-request-from-profile
    post-driver-check-request-body:
      description: the request to create a driver check
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/driver-check-request-from-pii'
              - $ref: '#/components/schemas/driver-check-request-from-profile'
    post-county-check-request-body:
      description: The request body for creating a county check
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/county_check_request'
    post-county-check-cancel-request-body:
      description: The request body for cancelling a county check
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/county_check_cancel_request'
    post-regulated-criminal-report-request-body:
      description: |
        The request body for creating a new regulated criminal report.
        Results are delivered asynchronously via webhook.
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/criminal_report_request_from_pii'
              - $ref: '#/components/schemas/criminal_report_request_from_profile'
    post-criminal-check-request-body:
      description: |
        The request body for creating a new criminal check.
        Results are delivered asynchronously via webhook.
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/criminal-check-request-from-pii'
              - $ref: '#/components/schemas/criminal-check-request-from-profile'
    post-token-request-body:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              client_id:
                type: string
                example: your-client-id
              client_secret:
                type: string
                example: your-client-secret
            required:
              - client_id
              - client_secret
  securitySchemes:
    get-bearer-token-using-oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.checkrtrust.com/v1/accounts/token
          scopes: {}
