KarmaCheck Cases API

openapi: 3.2.0
info:
  title: KarmaCheck Cases API
  description: 'All requests to the KarmaCheck API require a JSON Web Token (JWT) in the Authorization header. For an overview of the API and its authentication method, refer to the following topics:


    - [API basics](docs/overview/apis/api-overview.md)

    - [Authentication](docs/overview/apis/authentication.md)

    - [Environments](docs/overview/apis/environments.md)

    - [Status codes and errors](docs/overview/apis/errors.md)'
  version: '1.0'
  contact:
    name: KarmaCheck
    email: customersuccess@karmacheck.com
servers:
- description: Stage
  url: https://api-stage.karmacheck.io
- description: Prod
  url: https://api.karmacheck.io
security:
- JWT: []
tags:
- name: Cases
paths:
  /case/id/{caseId}/add/services:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of the case to add services to.
    post:
      tags:
      - Cases
      summary: Add to order
      description: Adds the requested services to the existing ordered case. The requested services must be part of the package for the case. The authentication token must be for the group that the case is owned by.
      operationId: post-case-id-caseId-add-services
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                Example 1:
                  services:
                  - id: 85307784-1f84-471a-8596-c8ea088c3a62
                  orderData:
                  - caseOrderDataTypeId: codt-education
                    serviceId: 85307784-1f84-471a-8596-c8ea088c3a62
                    metadata: {}
              properties:
                services:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The unique identifier of a service. See [Service](docs/reference/service.md) for a list of possible values.
                orderData:
                  type: array
                  items:
                    $ref: '#/components/schemas/CaseOrderData'
                orderConfig:
                  $ref: '#/components/schemas/OrderConfig'
                  description: Updated [configurations](docs/reference/order-configuration.md) that describe how to run certain screenings for the case. The current configurations for the case can be overridden only if there has not already been a screening dispatched where that configuration applies. For example, if a criminal screening was ordered during case creation, then `aliasNameConfiguration` cannot be updated.
            examples:
              Example 1:
                value:
                  services:
                  - id: service-cplc
                  orderData:
                  - caseOrderDataTypeId: codt-cplc
                    serviceId: service-cplc
                    metadata:
                      cplcId: 1d16c91d-c2da-47d1-b102-bd67d5b8b1ee
                      fields:
                      - fieldId: licenseNumber
                        value: L1234567
                      - fieldId: firstName
                        value: Matt
                      - fieldId: lastName
                        value: Williams
                      - fieldId: state
                        value: NY
                  orderConfig:
                    serviceConfigs:
                      9ac65633-b4c4-4062-875c-3556db9d2a08:
                        verificationMethod: psv-first
                      85307784-1f84-471a-8596-c8ea088c3a62:
                        verificationMethod: psv-first
        description: '`services` and `orderData` are both optional, but at least one of them is required to call this endpoint.'
      responses:
        '200':
          description: success
        '403':
          description: Unauthorized Request
        '422':
          description: 'The report is not ready yet, or a data issue such as:


            - The service specified is not allowed for the case.

            - A configuration is already set on the case for a dispatched service.'
        '500':
          description: Server Error
      security:
      - JWT: []
  /case/archive/{caseId}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of the case to archive.
    post:
      tags:
      - Cases
      summary: Archive case
      description: Archives a case so that it no longer appears in the KarmaCheck dashboard.
      operationId: post-case-archive-caseId
      parameters: []
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
              examples:
                Example 1:
                  value: success
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                type: string
              examples:
                Example 1:
                  value: Invalid case
        '500':
          description: Internal Server Error
      security:
      - JWT: []
  /case/id/{caseId}/action/beginprocessing:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      description: The ID of the case to begin processing.
      required: true
    put:
      tags:
      - Cases
      summary: Begin processing case
      description: 'Begins the processing of screenings for a case.


        This endpoint must be called when the onboarding of a case is complete, unless you are:


        - Sending invitation emails to the candidate so they can onboard.

        - Using the customer-provided PII flow to [create the case](paths/~1case~1create/post).


        In these instances, the case will begin processing as soon as the candidate information has been provided.'
      operationId: put-case-id-caseId-action-beginprocessing
      parameters: []
      responses:
        '200':
          description: OK
        '403':
          description: This response indicates a missing or invalid authentication token, or no access to the case.
        '422':
          description: This response means that the case is not ready to begin processing (for example, if a required testimony such as date of birth is missing), or that the case has already begun processing.
        '500':
          description: Internal Server Error
  /case/data/id/{caseDataId}/search/id/{searchId}/cancel:
    parameters:
    - schema:
        type: string
      name: caseDataId
      in: path
      required: true
      description: The ID of the case data containing the search.
    - schema:
        type: string
      name: searchId
      in: path
      required: true
      description: The ID of the search to cancel.
    post:
      tags:
      - Cases
      summary: Cancel case data search
      description: 'Endpoint to cancel individual case data search records.


        Currently supports cancelling education and employment searches.'
      operationId: post-case-data-id-caseDataId-search-id-searchId-cancel
      responses:
        '200':
          description: OK
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /case/create:
    post:
      tags:
      - Cases
      summary: Create case
      description: 'Orders a background check report and opens a case for tracking. The new case includes references to the package. Depending on the values entered in the request, the case goes through one of two flows:


        - **Candidate onboarding flow:** The new case will have an initial status of **Pending** and a secondary status of **Waiting for Authorization**. An invitation is emailed to the candidate, who is required to provide their personally identifiable information (PII) via the invitation email.

        - **Customer-provided PII flow:** All PII for the candidate is provided in the request body. Setting `autoProcess` to true initiates a case for the candidate and immediately begins processing.


        ### API Integration - Attributing a case to a specific user

        To provide additional insight for API integrations the Create Case API supports an optional header that allows an API customer to provide additional information about the end user that is initiating the API call through their integration.


        This optional header is only ever used if the API call has a valid authentication token.


        The optional header is `karmacheck-on-behalf-of` and the value that should be provided is an email address.


        When the `karmacheck-on-behalf-of` header contains an email address, the server will validate the email address provided, and if valid, the user associated with the email address will be recorded in the KarmaCheck system as the user that created the associated case.


        When validating the email address that is provided for this header:


        - if there is no user in the KarmaCheck system, then the value will simply be ignored and the case creation will be attributed to the authenticated API token itself.

        - if there is a user in the KarmaCheck system associated with the email address, but that user does not have the proper access to create a case for the package (or is not a user that is directly associated with the calling company) that is being requested then the API call will fail with a result that indicates that the user is not authorized to make that call. This error will occur even though the API token itself may be allowed to make the call but, because of the conflict, the call will be rejected.


        ### Restrictions

        The following restrictions exist when creating a case. Be sure to adhere to these restrictions when selecting a package or excluding services from the order (via `excludeServices`).


        #### Criminal and identity screening restrictions


        - SSN Trace is required when a County, State, or Federal Criminal Search is being ordered.

        - Cannot order Identity Verification and Identity And Liveliness Verification at the same time.

        - International Identity Verification cannot be ordered without other international screenings.

        - Must choose between US criminal screenings or international criminal screenings.

        - Must include International Identity Verification if Canadian Criminal Record Check or International Criminal Record Check is included.


        #### OHS and drug screening restrictions


        - Cannot order more than one type of TB test.

        - Cannot order DOT and non-DOT drug screenings in the same order.

        - Cannot order more than one non-DOT drug screening.

        - Only one urine drug screening can be selected for any order.

        - Cannot order both vaccine and titer for the same immunization type. This applies for each of the following immunization types: Varicella, Hepatitis A, Hepatitis B, and MMR.

        - OSHA Respirator/Fit to Wear Questionnaire is required when Respirator/Mask Fit Testing - Qualitative or Respirator/Mask Fit Testing - Quantitative is being ordered.

        - OHS and drug screenings are US-only and cannot be ordered with Canadian or international screenings.'
      operationId: post-case-create
      parameters:
      - name: karmacheck-on-behalf-of
        in: header
        required: false
        description: Optional. The email address of the end user who initiated this request through your integration. Only applied when the request is authenticated with an API User token. When the email matches a KarmaCheck user with the appropriate access, that user is recorded as the creator of the case instead of the API User. See the endpoint description for full validation behavior.
        schema:
          type: string
          format: email
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCase'
            examples:
              Candidate-provided PII flow:
                value:
                  packageId: a12ddee3-4fa5-43fc-9876-123a5d23a08b
                  email: matt.williams@example.com
                  givenName: Matt
                  familyName: Williams
              Customer-provided PII flow:
                value:
                  autoProcess: true
                  packageId: a12ddee3-4fa5-43fc-9876-123a5d23a08b
                  email: matt.williams@example.com
                  givenName: Matt
                  familyName: Williams
                  phone: '+18005550184'
                  candidateConsentProvided: true
                  candidateDisclosuresAndAuthorizationDocumentIds:
                  - 1234e9a3-8b78-4764-9fdd-12ce8c2b7f29
                  - b123427c-d3a1-4611-a4c3-7dc6e29b43aa
                  - ddde1e00-c1cd-4cb5-ade0-29ec1c3c4049
                  orderData:
                  - caseOrderDataTypeId: codt-govt-id
                    metadata:
                      govtId: 111-22-3333
                  - caseOrderDataTypeId: codt-dob
                    metadata:
                      dob: '1980-02-22'
                  - caseOrderDataTypeId: codt-current-candidate-address
                    metadata:
                      address1: 1 Main Street
                      city: New York
                      state: NY
                      postalCode: '10036'
                      country: US
                  orderConfig:
                    aliasNameConfiguration: alias-all+hits-only
                    serviceConfigs:
                      9ac65633-b4c4-4062-875c-3556db9d2a08:
                        verificationMethod: psv-first
                    contacts:
                    - email: defaultcontact@example.com
                      type: default
                      phone: 800-555-0170
                      name: Dana R.
                    - email: escalationcontact@example.com
                      type: escalation
                      name: Alex P.
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  caseId:
                    type: string
                  caseInvitationId:
                    type: string
              examples:
                Example 1:
                  value:
                    caseId: a09215ff-f46c-49a6-9767-762da1f3afd2
                    caseInvitationId: a2831b9e-897c-4971-85fd-a8328443ed63
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '409':
          description: A case for the specified email already exists in the group that the case is being created under.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cases:
                    type: array
                    items:
                      type: object
                      required:
                      - existingCaseId
                      - existingCaseCrStamp
                      - existingCasePackageId
                      - existingCasePackageName
                      - existingCaseStatusId
                      - existingCaseStatus
                      - modStamp
                      properties:
                        existingCaseId:
                          type: string
                        existingCaseCrStamp:
                          type: string
                        existingCasePackageId:
                          type: string
                        existingCasePackageName:
                          type: string
                        existingCaseStatusId:
                          type: string
                        existingCaseStatus:
                          type: string
                        existingCaseSecondaryStatusId:
                          type: string
                        existingCaseSecondaryStatus:
                          type: string
                        modStamp:
                          type: string
                          description: If the existing case is complete, this is when it completed.
                          format: date-time
              examples:
                Example 1:
                  value:
                    cases:
                    - existingCaseId: 74e1c0da-3106-4efb-b293-0f1648afae50
                      existingCaseCrStamp: '2024-05-23T00:58:06.000+00:00'
                      existingCasePackageId: 7e32983c-1ea5-4271-9832-231a51c740be
                      existingCasePackageName: Basic Check
                      existingCaseStatusId: d894b8a0-937e-46b1-8799-15bad611844f
                      existingCaseStatus: Pending
                      existingCaseSecondaryStatusId: 8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea
                      existingCaseSecondaryStatus: Waiting for Authorization
                      modStamp: '2024-05-23T00:58:06.000+00:00'
        '422':
          description: Bad data, or cannot replace an already completed case.
        '500':
          description: Internal Server Error
      security:
      - JWT: []
  /case/id/{caseId}/data/{serviceId}/pdf/download:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
    - schema:
        type: string
      name: serviceId
      in: path
      required: true
      description: The ID of the legal service.
    get:
      tags:
      - Cases
      summary: Download legal doc for case data
      description: Downloads the PDF document for the legal service requested for a case. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures).
      operationId: get-case-id-caseId-data-serviceId-pdf-download
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '422':
          description: Unable to download file.
        '500':
          description: Internal Server Error
      security:
      - JWT: []
  /case/id/{caseId}/preadverse/{type}/pdf/download:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
    - schema:
        type: string
        enum:
        - notice
        - report
      name: type
      in: path
      required: true
    get:
      tags:
      - Cases
      summary: Download pre-adverse action document
      description: Downloads the PDF file for the pre-adverse action notice or the case report that was active at the time of the pre-adverse action.
      operationId: get-case-id-caseId-preadverse-type-pdf-download
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '422':
          description: The case is not in an adverse action process.
        '500':
          description: Internal Server Error
      security:
      - JWT: []
  /jurisdiction/find/all:
    post:
      tags:
      - Cases
      summary: Find jurisdictions
      description: 'Retrieves a list of relevant county and federal district jurisdictions based on a set of city/county/state combinations.


        This list is needed when ordering a case, as it ensures that the case is ordered with the correct list of jurisdictions.'
      operationId: post-jurisdiction-find-all
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                counties:
                  type: array
                  items:
                    $ref: '#/components/schemas/JurisdictionCounties'
            examples:
              Example 1:
                value:
                  counties:
                  - city: Long Beach
                    state: CA
                    county: Los Angeles
                  - city: Newport Beach
                    state: CA
                    county: Orange
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/JurisdictionsFederalDistrictCourtAndCounty'
                      - type: object
                        required:
                        - jurisdictionType
                        properties:
                          jurisdictionType:
                            type: string
                            enum:
                            - federal-district
                            - county
              examples:
                Example 1:
                  value:
                    list:
                    - name: LOS ANGELES
                      stateCode: CA
                      state: CALIFORNIA
                      jurisdictionType: county
                    - name: ORANGE
                      stateCode: CA
                      state: CALIFORNIA
                      jurisdictionType: county
                    - name: California Central District Court
                      district: Central
                      stateCode: CA
                      state: CALIFORNIA
                      county: LOS ANGELES
                      jurisdictionType: federal-district
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      security:
      - JWT: []
  /case/list:
    parameters: []
    get:
      tags:
      - Cases
      summary: Get active cases
      description: 'Retrieves all active cases for the `groupProfileId` on the token used. The response includes summary-level information with IDs for accessing details using other endpoints.


        The cases are listed in descending order by `crStamp`. If any `crStamp` values are identical, the cases are then sorted by `caseStatusId`, followed by `caseSecondaryStatusId`.'
      operationId: get-case-list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - cases
                properties:
                  cases:
                    type: array
                    items:
                      $ref: '#/components/schemas/CaseSummary'
              examples: {}
        '403':
          description: This response indicates missing authorization, or valid authorization but insufficient permissions.
        '500':
          description: Internal Server Error
  /case/list/all:
    parameters: []
    get:
      tags:
      - Cases
      summary: Get all cases
      description: 'Retrieves all cases (both active and archived) for the `groupProfileId` on the token used. The response includes summary-level information with IDs for accessing details using other endpoints.


        The cases are listed in descending order by `crStamp`. If any `crStamp` values are identical, the cases are then sorted by `caseStatusId`, followed by `caseSecondaryStatusId`.'
      operationId: get-case-list-all
      parameters:
      - schema:
          type: string
        in: query
        name: userId
        description: If included, filters the cases to only those ordered by the specified user.
      - schema:
          type: string
        in: query
        name: packageId
        description: If included, filters the cases to only those ordered with the specified package.
      requestBody:
        content: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - cases
                properties:
                  cases:
                    type: array
                    items:
                      $ref: '#/components/schemas/CaseSummary'
              examples: {}
        '400':
          description: Invalid Request
        '403':
          description: This response indicates missing authorization, or valid authorization but insufficient permissions.
        '500':
          description: Internal Server Error
  /case/id/{caseId}/services:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
    get:
      tags:
      - Cases
      summary: Get all services for case
      description: Retrieves a list of all services ordered for a case.
      operationId: get-case-id-caseId-services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroupServicesCase'
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /candidate/info/case/id/{caseId}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The identifier of a case.
    get:
      tags:
      - Cases
      summary: Get candidate info for case
      description: Retrieves information about the candidate associated with the case.
      operationId: get-candidate-info-case-id-caseId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    candidate:
                      id: 9b766aef-be7f-4844-8b46-be7b53f74bf9
                      email: better_than_jim_halpert@gmail.com
                      password: '########'
                      givenName: Dwight
                      familyName: Schrute
                      govtId: XXX-XX-3333
                      phone: '+15702025821'
                      dob: '1966-01-20'
                      piiValidated: false
                      piiLocked: 1
                      enabled: true
                      crStamp: '2022-02-07T20:37:21.000+00:00'
                      modStamp: '2022-07-07T17:48:23.000+00:00'
                      secured: 1
                      candidateId: 9b766aef-be7f-4844-8b46-be7b53f74bf9
                      username: better_than_jim_halpert@gmail.com
                      accountNonExpired: true
                      accountNonLocked: true
                      credentialsNonExpired: true
                      fullName: Dwight Schrute
                required:
                - candidate
                properties:
                  candidate:
                    type: object
                    required:
                    - id
                    - email
                    - password
                    - givenName
                    - familyName
                    - fullName
                    - dob
                    - piiValidated
                    - piiLocked
                    - enabled
                    - crStamp
                    - modStamp
                    - secured
                    - candidateId
                    - username
                    - accountNonExpired
                    - accountNonLocked
                    - credentialsNonExpired
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                        format: email
                      password:
                        type: string
                        description: An obfuscated password.
                        example: '########'
                      givenName:
                        type: string
                      middleName:
                        type: string
                      familyName:
                        type: string
                      fullName:
                        type: string
                      govtId:
                        type: string
                        description: The candidate's Social Security number, which is obfuscated except for last 4 digits.
                        example: XXX-XX-3333
                      phone:
                        type: string
                      dob:
                        type: string
                        format: date
                        example: '1987-01-30'
                      piiValidated:
                        type: boolean
                      piiLocked:
                        type: integer
                        enum:
                        - 1
                        - 0
                        description: A boolean integer.
                      enabled:
                        type: boolean
                      crStamp:
                        type: string
                        format: date-time
                        example: '2024-07-22T23:48:24.000+00:00'
                      modStamp:
                        type: string
                        format: date-time
                        example: '2024-07-23T01:34:00.000+00:00'
                      secured:
                        type: integer
                        enum:
                        - 1
                        - 0
                        description: A boolean integer.
                      candidateId:
                        type: string
                      username:
                        type: string
                      accountNonExpired:
                        type: boolean
                      accountNonLocked:
                        type: boolean
                      credentialsNonExpired:
                        type: boolean
              examples:
                Example 1:
                  value:
                    candidate:
                      id: dfb411b1-ab2e-4076-9a22-9f2fda30b365
                      email: dani@example.com
                      password: '########'
                      givenName: Dani
                      familyName: Garcia
                      middleName: A.
                      govtId: XXX-XX-3333
                      phone: '+18005550126'
                      dob: '1995-05-04'
                      piiValidated: false
                      piiLocked: 1
                      enabled: true
                      crStamp: '2024-03-06T20:05:09.000+00:00'
                      modStamp: '2024-03-13T21:46:38.000+00:00'
                      secured: 0
                      credentialsNonExpired: true
                      accountNonExpired: true
                      accountNonLocked: true
                      candidateId: dfb411b1-ab2e-4076-9a22-9f2fda30b365
                      username: dani@example.com
                      fullName: Dani A. Garcia
        '403':
          description: Forbidden
        '404':
          description: 'The `caseId` provided is not associated with a case, or no candidate has been linked to the case yet.


            The latter scenario most likely means that for candidate onboarding cases, the candidate has not yet begun onboarding. For customer PII entry cases, a candidate might already exist under the email used, but other PII has mismatched.'
        '500':
          description: Internal Server Error
  /config/case/id/{caseId}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of the case for which to retrieve configurations.
    get:
      tags:
      - Cases
      summary: Get case configuration
      description: Returns the service configurations and contact information for a case. For information on how to create or update configuration options for a case, see [Create case](paths/~1case~1create/post) or [Add to order](paths/~1case~1id~1{caseId}~1add~1services/post).
      operationId: get-config-case-id-caseId
      responses:
        '200':
  

# --- truncated at 32 KB (213 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/karmacheck/refs/heads/main/openapi/karmacheck-cases-api-openapi.yml