Checkr Employment Verification API

openapi: 3.2.0
info:
  version: v1
  title: Checkr.com API Docs Employment Verification 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: Employment Verification
  description: 'Use an Employment Verification to verify a candidate’s employment history for the last three

    employers, or the last seven years.


    For this screening, candidates are asked to supply their employment history. Checkr then

    attempts to verify the information. After three failed attempts (itemized in the logs),

    Checkr generates an exception, and asks the candidate to upload supporting documentation.

    Once the document is uploaded, the verification process will begin again.


    For more information, please see

    Employment Verification

    in the Checkr Help Center.'
paths:
  /employment_verifications/{id}:
    parameters:
    - name: id
      in: path
      description: ID of the Employment Verification to retrieve.
      required: true
      schema:
        type: string
    get:
      tags:
      - Employment Verification
      summary: Retrieve an existing Employment Verification
      description: Returns an existing Employment Verification with the input ID.
      operationId: getEmploymentVerification
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/EmploymentVerification'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-codeSamples:
      - lang: curl
        source: "$ curl -X GET https://api.checkr.com/v1/employment_verifications/59690155331711004e252cd8 \\\n    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:\n"
components:
  schemas:
    ResourceURI:
      type: string
      description: URI of the resource.
      readOnly: true
    ResultPayload:
      type: object
      properties:
        verified:
          type: boolean
          example: true
        comments:
          type: string
        ignored:
          type:
          - string
          - 'null'
          example: null
    EmploymentVerification:
      allOf:
      - $ref: '#/components/schemas/ScreeningsGenericPayload'
      - type: object
        properties:
          object:
            enum:
            - employment_verification
          uri:
            example: /v1/employment_verifications/595511af261066005170f471
          status:
            allOf:
            - $ref: '#/components/schemas/ScreeningStatus'
            - example: consider
          result:
            allOf:
            - $ref: '#/components/schemas/ScreeningResult'
            - example: consider
          turnaround_time:
            example: 603216
          includes_canceled:
            allOf:
            - $ref: '#/components/schemas/IncludesCanceledBoolean'
            - example: true
          records:
            type: array
            description: Array of CandidateEmploymentHistory objects.
            items:
              type: object
              properties:
                id:
                  type: string
                  example: 592311d2113adf7e9c9f66b8
                result:
                  type: object
                  properties:
                    start_date:
                      allOf:
                      - $ref: '#/components/schemas/ResultPayload'
                      - type: object
                        properties:
                          comments:
                            example: '2016-06-01'
                    end_date:
                      allOf:
                      - $ref: '#/components/schemas/ResultPayload'
                      - type: object
                        properties:
                          comments:
                            example: '2017-05-01'
                    position:
                      allOf:
                      - $ref: '#/components/schemas/ResultPayload'
                      - type: object
                        properties:
                          verified:
                            example: true
                          comments:
                            example: Software Development Engineer
                          ignored:
                            example: manual
                    contract_type:
                      allOf:
                      - $ref: '#/components/schemas/ResultPayload'
                      - type: object
                        properties:
                          comments:
                            example: Full Time
                          ignored:
                            example: package
                    salary:
                      allOf:
                      - $ref: '#/components/schemas/ResultPayload'
                      - type: object
                        properties:
                          verified:
                            example: true
                          comments:
                            example: '100000'
                    questions:
                      type: array
                      description: List of questions for the candidate's employer.
                      items:
                        type: object
                        properties:
                          sort_number:
                            description: The position of the question within the list.
                            type: integer
                            example: 1
                          text:
                            description: The question that was asked.
                            type: string
                            example: What is the documented reason for the employee's departure?
                          response:
                            description: The answer received in response to the question.
                            type: string
                            example: They resigned.
                employer:
                  $ref: '#/components/schemas/Employer'
                events:
                  type: array
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                        example: started
                      created_at:
                        type: string
                        example: '2017-06-29T14:42:44Z'
                      type:
                        type: string
                        example: verification_start
                status:
                  type: string
                  enum:
                  - pending
                  - clear
                  - consider
                  example: consider
                cancellation_reason:
                  type:
                  - string
                  - 'null'
                  description: The reason the screening was canceled.
                  enum:
                  - complete_now_customer_requested
                  - no_history_required_information
                  - international_entry_not_supported
                  example: customer_requested_complete_now
                cancellation_reason_description:
                  type:
                  - string
                  - 'null'
                  description: Description of the `cancellation_reason` for the screening.
                  enum:
                  - Customer requested Complete Now prior to screening completion
                  - Candidate declared no history
                  - Screening does not support international entries
                  example: Customer requested Complete Now prior to screening completion
    AssessmentAttribute:
      type:
      - string
      - 'null'
      description: 'The assessment for this screening. This field will be non-null only for Assess-enabled accounts. For accounts with Assess enabled, it will be null for reports completed before Assess was enabled, and null for a short time after report completion while the account''s Assess rules are applied.

        '
      enum:
      - eligible
      - review
      - escalated
      example: eligible
    ScreeningResult:
      type:
      - string
      - 'null'
      description: Outcome of the screening.
      enum:
      - clear
      - consider
    ScreeningStatus:
      type: string
      description: Status of the screening.
      enum:
      - pending
      - complete
    IncludesCanceledBoolean:
      type:
      - boolean
      - 'null'
      description: If account has opted in to report lifecycle phase two, indicates the presence of canceled histories. Otherwise, `null`.
      enum:
      - true
      - false
    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.
    Employer:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
          enum:
          - employer
          readOnly: true
        uri:
          allOf:
          - $ref: '#/components/schemas/ResourceURI'
          example: /v1/candidates/e44aa283528e6fde7d542194/employers/ca27df84be5b50dfa7ee1cda
        candidate_id:
          type: string
          description: ID of the Candidate being screened.
          pattern: '[a-zA-Z0-9 -''.,]*'
          example: xxx
          minLength: 1
        name:
          type: string
          pattern: '[a-zA-Z0-9 -''.,]*'
          description: Candidate’s employer’s name.
          example: Checkr
          minLength: 1
        position:
          type: string
          description: Candidate’s position or title.
          example: Software Engineer
        salary:
          type: integer
          description: Candidate’s gross salary in dollars annually.
          example: 10000
        contract_type:
          type: string
          description: Candidate’s contract type.
          enum:
          - full_time
          - part_time
          - contract
          - internship
          example: full_time
        do_not_contact:
          type: boolean
          default: false
          description: If `true`, the employer will not be contacted about the Candidate.
          example: false
        start_date:
          type: string
          description: Candidate’s start date with the employer.
          format: date
          example: '2016-06-01'
        end_date:
          type: string
          description: Candidate’s end date with the employer.
          format: date
          example: '2017-05-01'
        employer_url:
          type: string
          description: Employer’s website.
          example: www.employer.com
        address:
          $ref: '#/components/schemas/Address'
        manager:
          type: object
          properties:
            name:
              type: string
              description: Candidate's manager's name.
              example: Joe Smith
            title:
              type: string
              description: Candidate's manager's title.
              example: Engineering Manager
            email:
              type: string
              description: Candidate's manager's email address.
              example: joesmith@checkr.co
            phone:
              type: string
              description: Candidate's manager's phone number.
              example: 212-555-1234
    Address:
      type: object
      properties:
        street:
          type: string
          pattern: '[a-zA-Z0-9 -''.,]*'
          description: Street address.
          example: 123 Main St.
        unit:
          type: string
          pattern: '[a-zA-Z0-9 -''.,]*'
          description: House, building or apartment number.
          example: 2000
        city:
          type: string
          pattern: '[a-zA-Z0-9 -''.,]*'
          description: City.
          example: San Francisco
        state:
          type: string
          description: State.
          example: CA
        zipcode:
          type: string
          description: 5-digit zip code.
          example: '90401'
        country:
          type: string
          description: 'Country.


            Format: `ISO 3166-1 alpha-2`

            '
          example: US
    ScreeningsGenericPayload:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
        uri:
          allOf:
          - $ref: '#/components/schemas/ResourceURI'
        status:
          type: string
          description: 'Status of the screening.

            '
          enum:
          - pending
          - complete
          - canceled
          - suspended
          example: complete
        result:
          type:
          - string
          - 'null'
          description: Result of the screening.
          enum:
          - clear
          - consider
          example: clear
        assessment:
          allOf:
          - $ref: '#/components/schemas/AssessmentAttribute'
        created_at:
          type: string
          description: Time at which the screening was created.
          format: date-time
          example: '2014-01-18T12:34:00Z'
        completed_at:
          type: string
          description: Time at which the screening was completed.
          format: date-time
          example: '2014-01-18T12:35:30Z'
        turnaround_time:
          type: integer
          description: Number of seconds the screening took to complete, calculated from `created_at` to `completed_at`.
        cancellation_reason:
          type: string
          description: See [cancellation reasons](#section/Reference/Cancellation-Reasons) section for possible values.
          example: complete_now_customer_requested
        cancellation_reason_description:
          type: string
          description: See [cancellation reasons](#section/Reference/Cancellation-Reasons) section for possible values.
          example: Customer requested Complete Now prior to screening completion
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Bad authentication error
  responses:
    EmploymentVerification:
      description: Employment Verification details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmploymentVerification'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
  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)