Checkr Adverse Actions API

openapi: 3.2.0
info:
  version: v1
  title: Checkr.com API Docs Adverse Actions API
  license:
    name: Proprietary
    url: https://www.checkr.com
  contact:
    name: Checkr
    email: clients@checkr.com
    url: https://checkr.com
  description: '# Introduction


    Checkr is a modern, RESTful API-driven background screening service. The Checkr API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages JSON in all responses passed back to customers. Checkr is used by over 10,000 customers in a wide variety of industries, and supports a range of screening products and candidate workflows. For a full list of our screenings, please see the Checkr Screenings section below or read the Checkr Help Center articles on Screening Types. This Programming Guide is designed to help customers get up-and-running with Checkr''s background screening services, both by providing the necessary context to understand the background screening industry and its regulations, and by giving technical guidance on how to work with the Checkr API. **Note:** The cURL command is used for all examples in the Checkr API documentation. ### Other resources


    For information about using the Checkr Dashboard, and compliance and regulatory aspects of background checks, visit the Checkr Help Center. For a more targeted set of Checkr Dashboard learning paths for talent sourcing roles like Recruiters, Adjudicators, or Program Administrators, please see the Checkr Learning Center. ## Understand the screening process


    Checkr follows a standardized screening process:


    1. Customer requests a background check. 2. Candidate is presented with and signs the necessary disclosures and authorizations, and submits the requested Personally Identifiable Information (PII). - With the Checkr-Hosted Apply Flow, the candidate signs disclosures and authorizations and enters their own PII. - With a custom self-hosted flow, the Checkr customer collects the required authorizations, and passes Checkr candidate PII using the Checkr API. 3. Checkr conducts an SSN Trace, and collects associated addresses. 4. Checkr runs searches or verifications based on the screening Packages requested. 5. Checkr applies appropriate compliance filters based on the customer’s settings and candidate’s provided residence to determine which records to show, and returns a finalized report to the customer. 6. If there is a record on the report, the customer Engages or Adverse Actions the Candidate, based on an individualized assessment of the candidate''s report. ### 1. Request a background check


    To initiate a background check, a customer provides Checkr their candidate''s email address (for a Checkr-Hosted Apply Flow) or the candidate''s PII (for a self-hosted flow). For more information on ways to achieve this, please see Designing your workflow. ### 2. Candidate signs disclosures and authorizations


    Under the U.S. Fair Credit Reporting Act (FCRA), customers are obligated to collect consent from their candidates when running background checks through Checkr or any other Consumer Reporting Agency (CRA). The Checkr-Hosted Apply Flow presents candidates with fields in which the requested PII may be entered, and collects candidate information on behalf of the customer. Checkr will also present disclosures and authorizations to the candidate, and enable eSignature to capture consent, on behalf of customers using this flow with the Checkr Dashboard or email invitation flow. Custom self-hosted flows collect candidate PII, and pass the information to Checkr using the Checkr API. Customers creating a self-hosted flow will receive guidance from the Checkr team on setting up a similar process as required. ### 3. Checkr runs an SSN Trace


    Checkr runs an SSN Trace to match the candidate’s provided PII with existing credit header data mapped to the SSN. This process yields a list of names and addresses associated with the entered SSN, which can be used to supplement the background check process. At this point Checkr also conducts some initial data comparisons to check that critical pieces of information, like a candidate''s submitted Date of Birth (DOB) and SSN, align with information held on file by the credit bureaus.'
servers:
- url: https://api.checkr.com/v1
  description: Main server
tags:
- name: Adverse Actions
  description: 'Adverse Actions are initiated by Checkr customers if something is returned on a Candidate’s

    report that requires further investigation. When an Adverse Action is initiated, the candidate

    must be informed, and given time to address the issues raised.


    National and local laws control the Adverse Action process and define the sequence and timing

    with which it must process. Please work with your legal council to ensure that your process is

    compliant.


    For more information, see

    The Adverse Actions Process

    in the Checkr Help Center.'
paths:
  /adverse_actions/{id}:
    parameters:
    - name: id
      in: path
      description: ID of the Adverse Action.
      required: true
      schema:
        type: string
    get:
      tags:
      - Adverse Actions
      summary: Retrieve an existing Adverse Action
      description: Returns an existing Adverse Action with the input ID.
      operationId: getAdverseAction
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/AdverseAction'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-codeSamples:
      - lang: curl
        source: "$ curl -X GET https://api.checkr.com/v1/adverse_actions/57ed51e57619e8002a6683f2 \\\n    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:\n"
    delete:
      tags:
      - Adverse Actions
      summary: Cancel an existing Adverse Action
      description: Cancels an existing Adverse Action.
      operationId: cancelAdverseAction
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/AdverseActionCanceled'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-codeSamples:
      - lang: curl
        source: "$ curl -X DELETE https://api.checkr.com/v1/adverse_actions/e44aa283528e6fdaa9542194 \\\n    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:\n"
  /reports/{report_id}/adverse_actions:
    post:
      tags:
      - Adverse Actions
      summary: Create a new Adverse Action
      description: 'Creates a new Adverse Action.


        Note: Report must be in a `consider` status and cannot have any existing Adverse Actions that have not been canceled.'
      operationId: createAdverseAction
      security:
      - basic_auth: []
      parameters:
      - name: report_id
        in: path
        required: true
        description: The ID of the Report for which the Adverse Action will be created.
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/AdverseActionCreate'
      responses:
        '200':
          $ref: '#/components/responses/AdverseActionCreated'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-codeSamples:
      - lang: curl
        source: "$ curl -X POST https://api.checkr.com/v1/reports/b861a56db1b1b89692dd6118/adverse_actions \\\n    -u 83ebeabdec09f6670863766f792ead24d61fe3f9: \\\n    -d post_notice_scheduled_at=2016-10-07T12:34:00Z \\\n    -d 'adverse_item_ids[]=57ed4ce3057e0b002adc6d90&adverse_item_ids[]=57ed4ce3057e0b002adc6d91'\n    -d 'medium={\"email\": {\"priority\": 1, \"required\": true}, \"postal\": {\"priority\": 0, \"required\": false}}'\n"
components:
  schemas:
    ResourceURI:
      type: string
      description: URI of the resource.
      readOnly: true
    AdverseItemAssessment:
      type: object
      description: 'Information about the Assessment of the Adverse Item.


        Included only if Assess is enabled for the account.

        '
      properties:
        value:
          $ref: '#/components/schemas/AssessmentValue'
        rule:
          $ref: '#/components/schemas/Rule'
    BadRequestError:
      type: object
      properties:
        error:
          type: string
          example: Dl number 'F211165' does not match the license number format in CA
    Rule:
      type: object
      description: 'Description of the applied Rule, as defined for your account.

        '
      properties:
        name:
          type: string
          description: The name of the Rule, as defined for your account.
          example: Allow dismissed charges rule
        type:
          type: string
          description: The type of the Rule.
          enum:
          - count
          - custom
          - default
          - lookback_period
          - fairness_and_compliance
          - undefined
          example: lookback_period
    ForbiddenError:
      type: object
      properties:
        error:
          type: string
          example: You do not have permission to access the requested resource
    ResourceId:
      type: string
      example: e44aa283528e6fde7d542194
      readOnly: true
      description: ID of the resource.
    AssessmentValue:
      type: string
      example: eligible
      enum:
      - eligible
      - review
      - escalated
    AdverseAction:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
          enum:
          - adverse_action
          readOnly: true
        uri:
          allOf:
          - $ref: '#/components/schemas/ResourceURI'
          example: /v1/adverse_actions/57ed51e57619e8002a6683f2
        created_at:
          type: string
          description: Time at which the Adverse Action was created.
          format: date-time
          example: '2016-09-29T17:39:49Z'
        delivery:
          type: object
          description: Details about the delivery state of the Adverse Action.
          properties:
            state:
              type: string
              description: Status of delivery for the Adverse Action.
              enum:
              - none
              - queued
              - sent
              - delivered
              - error
              - unknown
              - unopened
              example: delivered
            reason:
              type: string
              description: Reason for the current state. Typically, this an error message, e.g. the raw response from an email provider.
              example: The email account that you tried to reach does not exist. Please double-check the recipient's email address for typos or unnecessary spaces.
            updated_at:
              type: string
              description: Time at which the delivery state was updated.
              format: date-time
              example: '2016-09-29T17:39:49Z'
        status:
          type: string
          description: Status of the Adverse Action.
          enum:
          - pending
          - complete
          - dispute
          - canceled
          example: pending
        report_id:
          type: string
          description: ID of the Report causing this adverse action.
          example: b861a56db1b1b89692dd6118
        post_notice_scheduled_at:
          type: string
          description: 'Timestamp at which the post Adverse Action notification will be sent. This time is

            dependent on the time at which the Pre-Adverse Action was created, and related settings

            within your Checkr system.

            '
          format: date-time
          example: '2016-10-07T12:34:00Z'
        post_notice_ready_at:
          type: string
          description: 'Timestamp after which the post notice can be sent. (Often 7 days after `created_at`.)

            '
          format: date-time
          example: '2016-10-06T17:39:48Z'
        canceled_at:
          type:
          - string
          - 'null'
          description: Time at which the Adverse Action was canceled.
          format: date-time
          example: null
        adverse_items:
          type: array
          items:
            $ref: '#/components/schemas/AdverseItem'
          description: Array of Adverse Items on which the Action is based.
        individualized_assessment_engaged:
          type: boolean
          default: false
    AdverseItem:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
          description: Defines the object type.
          enum:
          - adverse_item
          readOnly: true
        text:
          type: string
          description: Human-readable description of the Adverse Item.
          example: 'License status: Suspended'
        assessment:
          $ref: '#/components/schemas/AdverseItemAssessment'
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Bad authentication error
  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    AdverseActionCanceled:
      description: Adverse Action was successfully canceled
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdverseAction'
    AdverseAction:
      description: Adverse Action details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdverseAction'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    AdverseActionCreated:
      description: Adverse Action was successfully created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdverseAction'
  requestBodies:
    AdverseActionCreate:
      content:
        application/json:
          schema:
            type: object
            required:
            - adverse_item_ids
            properties:
              post_notice_scheduled_at:
                type: string
                format: date-time
                description: Time at which the Post-Adverse Action notification will be sent. Default is 7 days after creation.
                example: '2016-10-07T12:34:00Z'
              adverse_item_ids:
                type: array
                items:
                  type: string
                description: IDs of Adverse Items selected for the Adverse Action.
              medium:
                type: object
                description: 'The medium through which the Adverse Action notification should be sent.

                  '
                properties:
                  email:
                    type: object
                    description: 'The email medium is used to send an adverse action via email to the candidate.

                      '
                    properties:
                      priority:
                        type: number
                        description: The priority setting dictates whether the adverse action should be sent through this medium. A priority of 1 means the adverse action will be sent, while a priority of 0 means it will not be sent through this medium.
                        example: 1
                      required:
                        type: boolean
                        description: The "required" setting specifies whether an adverse action must be sent. If set to true, it means the adverse action must be sent through this medium. If set to false, sending the adverse action through this medium is optional.
                        example: true
                  postal:
                    type: object
                    description: 'The postal medium is used to send an adverse action via physical mail to the candidate.

                      '
                    properties:
                      priority:
                        type: number
                        description: The priority setting dictates whether the adverse action should be sent through this medium. A priority of 1 means the adverse action will be sent, while a priority of 0 means it will not be sent through this medium.
                        example: 0
                      required:
                        type: boolean
                        description: The "required" setting specifies whether an adverse action must be sent. If set to true, it means the adverse action must be sent through this medium. If set to false, sending the adverse action through this medium is optional.
                        example: false
      required: true
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
x-tagGroups:
- name: Resources
  tags:
  - Account
  - Users
  - Hierarchy (Enabled by request)
  - Nodes
  - Candidates
  - Reports
  - Packages
  - Invitations
  - Geos
  - Programs
  - Assessments
  - Subscriptions
  - Continuous Checks
  - Adverse Actions
  - Adverse Items
  - Verifications
  - Documents
  - Driver Licenses
  - Professional Licenses
  - Schools
  - Employers
  - Counties
  - Report Tags
  - Report Addresses
  - Report ETA
  - Candidate Stories
  - SSN
  - Webhooks
  - Candidate Postal Address
- name: Screenings
  tags:
  - SSN Trace
  - Sex Offender Registry Search
  - Global Watchlist Search
  - National Criminal Search
  - Federal Criminal Search
  - Federal District Criminal Search
  - Federal Civil Search
  - Federal District Civil Search
  - County Criminal Search
  - State Criminal Search
  - Motor Vehicle Report
  - Drug & Alcohol Clearinghouse Search
  - Education Verification
  - Employment Verification
  - Personal Reference Verification
  - Professional Reference Verification
  - Professional License Verification
  - International Adverse Media Search
  - International Criminal Search
  - International Education Verification
  - International Employment Verification
  - International Global Watchlist Search
  - International Identity Document Validation
  - International Motor Vehicle Report
  - FACIS Search
- name: Form I-9
  tags:
  - Getting Started
  - Forms I-9
  - Worksites
x-provenance:
  method: harvested
  publisher: Checkr
  source: https://api.redocly.com/registry/bundle/checkr/Checkr%20Public%20API/v1/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)