Checkr Candidate Stories API

openapi: 3.2.0
info:
  version: v1
  title: Checkr.com API Docs Candidate Stories 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: Candidate Stories
  description: 'Candidate Stories allows candidates with records the opportunity to share additional context

    about themselves and their background checks. Once submitted, these stories will be available

    to customers in the candidate’s report in the Checkr Dashboard.


    For more information, please see

    Candidate Stories: Improving understanding of the past and present

    in the Checkr Help Center.'
paths:
  /candidate_stories/{id}:
    parameters:
    - name: id
      in: path
      description: ID of the Candidate Story.
      required: true
      schema:
        type: string
    get:
      tags:
      - Candidate Stories
      summary: Retrieve a Candidate Story
      description: Returns the existing Candidate Story corresponding to the input ID.
      operationId: getCandidateStory
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/CandidateStory'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    delete:
      tags:
      - Candidate Stories
      summary: Delete a Candidate Story
      description: Deletes the existing Candidate Story corresponding to the input ID.
      operationId: deleteCandidateStory
      security:
      - basic_auth: []
      responses:
        '200':
          $ref: '#/components/responses/CandidateStoryDeleted'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /reports/{report_id}/candidate_stories:
    post:
      tags:
      - Candidate Stories
      summary: Create a new Candidate Story
      description: Create a new Candidate Story for the input `report_id`.
      operationId: createCandidateStory
      security:
      - basic_auth: []
      parameters:
      - name: report_id
        in: path
        required: true
        description: Create an candidate story for the input `report_id`.
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/CandidateStoryCreate'
      responses:
        '200':
          $ref: '#/components/responses/CandidateStoryCreated'
        '400':
          $ref: '#/components/responses/EntityConfigurationLimitExceeded'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
components:
  schemas:
    ResourceURI:
      type: string
      description: URI of the resource.
      readOnly: true
    CandidateStory:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
          enum:
          - candidate_story
          readOnly: true
        uri:
          allOf:
          - $ref: '#/components/schemas/ResourceURI'
          example: /v1/candidate_stories/e44aa283528e6fde7d542194
        report_id:
          type: string
          description: ID of the Report to which the Candidate Story is linked.
          example: af3393b7d751206c7c67b6e5
        record:
          type:
          - object
          - 'null'
          description: 'Simplified representation of linked record.

            If `null`, Candidate Story is considered general information about the Candidate.

            '
          properties:
            id:
              type: string
              description: Record ID
              example: 4e2a551f79e0095b35d4d3ca
            case_number:
              type:
              - string
              - 'null'
              description: Case number, if existing
              example: NMND78D
            charge:
              type:
              - string
              - 'null'
              description: Charge description, if existing
              example: LIGHT OFFENSE
            offense_date:
              type:
              - string
              - 'null'
              format: date
              description: Offense date, if existing
              example: '2020-01-20'
            location:
              type:
              - string
              - 'null'
              description: Location of the Record, can be a State, or a City and a State, if existing
              example: San Mateo, CA
        content:
          type: string
          description: Additional information provided by Candidate.
          example: Since my case, I have received the following certifications (see attachments)
        created_at:
          type: string
          description: Time at which the Candidate Story was created.
          format: date-time
          example: '2020-04-17T07:48:34Z'
        documents:
          description: Attached documents provided by Candidate.
          type: array
          items:
            $ref: '#/components/schemas/CandidateStoryDocument'
    BadRequestError:
      type: object
      properties:
        error:
          type: string
          example: Dl number 'F211165' does not match the license number format in CA
    CandidateStoriesLimitError:
      type: object
      properties:
        error:
          type: string
          example: Candidate stories limit exceeded
    ForbiddenError:
      type: object
      properties:
        error:
          type: string
          example: You do not have permission to access the requested resource
    CandidateStoryDocument:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        object:
          type: string
          enum:
          - document
          readOnly: true
        type:
          type: string
          description: The type of Document.
          enum:
          - candidate_story_document
          example: candidate_story_document
        created_at:
          type: string
          description: Time at which the Document was created.
          format: date-time
          example: '2020-04-17T07:48:01Z'
        download_uri:
          type: string
          description: JSON encoded URL of the document. This URL is valid for 15 minutes.
          example: https://checkr-documents.checkr.com/download_path
        filesize:
          type: integer
          description: File’s size in bytes.
          example: 8576
        filename:
          type: string
          description: File’s name.
          example: proof_of_rehabilitation.pdf
        content_type:
          type: string
          description: File’s content type.
          example: image/pdf
    ResourceId:
      type: string
      example: e44aa283528e6fde7d542194
      readOnly: true
      description: ID of the resource.
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Bad authentication error
    CandidateStoryDocumentsLimitError:
      type: object
      properties:
        error:
          type: string
          example: Candidate story documents limit exceeded
  responses:
    CandidateStoryCreated:
      description: Candidate Story was successfully created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CandidateStory'
    CandidateStory:
      description: Candidate Story details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CandidateStory'
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    CandidateStoryDeleted:
      description: Candidate Story was successfully deleted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CandidateStory'
    EntityConfigurationLimitExceeded:
      description: Limit exceeded
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/CandidateStoriesLimitError'
            - $ref: '#/components/schemas/CandidateStoryDocumentsLimitError'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
  requestBodies:
    CandidateStoryCreate:
      content:
        application/json:
          schema:
            type: object
            required:
            - content
            - documents
            properties:
              content:
                type: string
                description: Additional information provided by Candidate.
                example: Since my case, I have received the following certifications (see attachments)
              record_id:
                type: string
                description: 'ID of the Record existing on a Screening to which the Candidate Story is linked.

                  When no record ID is provided, the Candidate Story is considered General Information.

                  '
                example: af3393b7d751206c7c67b6e5
              documents:
                type: array
                description: An array of documents to attach to the Candidate Story. Can be empty.
                items:
                  type: object
                  properties:
                    filename:
                      type: string
                      description: File name
                      example: evidence_of_rehab.pdf
                    tempfile:
                      type: string
                      description: Accessible resource from which the document will be copied.
                      example: https://tempfilebucket.aws.example.com/abYwtudnakfnafl
                    type:
                      type: string
                      description: Document MIME type
                      enum:
                      - application/pdf
                      - image/bmp
                      - image/gif
                      - image/heic
                      - image/jpeg
                      - image/jpg
                      - image/png
                      - image/tiff
                      example: application/pdf
      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)