Checkr SSN Trace API

openapi: 3.2.0
info:
  version: v1
  title: Checkr.com API Docs SSN Trace 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: SSN Trace
  description: 'SSN Trace is typically the first screening run, and is used to verify that

    the input SSN exists, determine where and when it was issued, and to compile

    a list of all known aliases associated with the SSN. This Trace is also used to generate

    a list of all known addresses recorded by credit agencies for the SSN for the last 7 years.


    An SSN Trace may be used to determine which additional jurisdictions should be searched for

    the candidate, based on the list of known addresses returned.


    If the platform detects an issue with the SSN Trace run (data mismatch, absence of data,

    or inclusion of the SSN on the death master file), Checkr may issue an exception and ask

    the candidate to either re-enter their SSN or upload other supporting documentation.


    Note: Information returned by this search is not a part of the consumer report and may not be used for FCRA purposes, including eligibility determinations under the FCRA


    For more information, please see

    SSN Trace

    in the Checkr Help Center.'
paths:
  /ssn_traces/{id}:
    parameters:
    - name: id
      in: path
      description: ID of the SSN Trace to retrieve.
      required: true
      schema:
        type: string
    get:
      tags:
      - SSN Trace
      summary: Retrieve an existing SSN Trace
      description: Returns an existing SSN Trace with the input ID.
      operationId: getSsnTrace
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/SsnTrace'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-codeSamples:
      - lang: curl
        source: "$ curl -X GET https://api.checkr.com/v1/ssn_traces/539fd88c101897f7cd000001 \\\n    -u 83ebeabdec09f6670863766f792ead24d61fe3f9:\n"
components:
  schemas:
    ResourceURI:
      type: string
      description: URI of the resource.
      readOnly: true
    ScreeningStatusNonReportable:
      type: string
      description: Status of the screening.  Screenings completed before April 2021 may return `"clear"` or `"consider"`.
      enum:
      - pending
      - complete
    ScreeningsWithNullResult:
      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.


            <font color="red">Note:</font> The `result` parameter will always return a `null` value because this is a non-reportable screening.

            '
          enum:
          - clear
          - consider
          example: clear
        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: null
        cancellation_reason_description:
          type: string
          description: See [cancellation reasons](#section/Reference/Cancellation-Reasons) section for possible values.
          example: null
    SsnTrace:
      allOf:
      - $ref: '#/components/schemas/ScreeningsWithNullResult'
      - type: object
        properties:
          object:
            enum:
            - ssn_trace
          uri:
            example: /v1/ssn_traces/539fd88c101897f7cd000001
          status:
            allOf:
            - $ref: '#/components/schemas/ScreeningStatusNonReportable'
            - example: complete
          result:
            type:
            - string
            - 'null'
            description: Outcome of the screening.  Screenings completed before April 2021 may return `"clear"` or `"consider"`.
            example: null
          turnaround_time:
            example: 90
          ssn:
            type: string
            description: Candidate’s social security number. This value will be redacted in all return calls, except for the last four digits.
            example: XXX-XX-4645
          no_data:
            type: boolean
            description: No data was returned for the input Candidate PII.
            default: false
          dob_mismatch:
            type: boolean
            description: If true, the name on the SSN Trace matches the candidate's provided information, but the DOB does not.
            default: false
          name_mismatch:
            type: boolean
            description: If true, the DOB associated with the addresses returned from the SSN Trace matches the candidate's input DOB, but the name does not.
            default: false
          data_mismatch:
            type: boolean
            description: If true, information returned from the SSN Trace does not match any of the candidate’s provided information.
            default: false
          thin_file:
            type: boolean
            description: No information found.
            default: false
          invalid_issuance_year:
            type: boolean
            description: If true, the input SSN has a year of issuance that precedes the candidate's reported year of birth.
            default: false
          death_index:
            type: boolean
            description: If true, the input SSN is listed on the Social Security Administration's “Death Master File”.
            default: false
          ssn_already_taken:
            type: boolean
            description: If true, another Candidate with same SSN already exists in our system.
            default: false
          issued_year:
            type: integer
            description: The year the ID was issued.
            example: 1993
          issued_state:
            type: string
            description: The US state where the ID was issued.
            example: CA
          addresses:
            type: array
            description: This field has been deprecated and will return an empty array.
          aliases:
            type: array
            description: This field has been deprecated and will return an empty array.
    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.
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Bad authentication error
  responses:
    SsnTrace:
      description: SSN Trace details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsnTrace'
    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)