KarmaCheck Candidate onboarding API

openapi: 3.2.0
info:
  title: KarmaCheck Candidate onboarding 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: Candidate onboarding
paths:
  /case/id/{caseId}/canadadisclosure/{language}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of a case.
    - $ref: '#/components/parameters/language'
    post:
      tags:
      - Candidate onboarding
      summary: Acknowledge Canada Disclosure
      description: Submits acknowledgement of a Canada Disclosure document for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosure.
      operationId: post-case-id-caseId-canadadisclosure-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalAcknowledgmentDisclosure'
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case doesn't have the specified disclosure service, or the candidate already acknowledged it.
        '500':
          description: Internal Server Error
    get:
      tags:
      - Candidate onboarding
      summary: Get Canada Disclosure
      description: Retrieves a Canada Disclosure document to present to the candidate so that the candidate can acknowledge and continue the onboarding process. If the candidate has already acknowledged the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details of the previous acknowledgement can be retrieved. This can also be used to determine whether the candidate can skip this specific disclosure step if they leave and then continue their onboarding later or on another device, for example.
      operationId: get-case-id-caseId-canadadisclosure-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - alreadyAck
                - title
                - body
                - authorizationStatement
                - authorizationObject
                properties:
                  alreadyAck:
                    type: boolean
                    description: True if the candidate already acknowledged the disclosure; false otherwise.
                  title:
                    type: string
                    description: Escaped HTML.
                  header:
                    type: string
                    description: Escaped HTML.
                  body:
                    type: string
                    description: Escaped HTML.
                  authorizationStatement:
                    type: string
                    description: Escaped HTML.
                  authorizationObject:
                    type: object
                    required:
                    - sections
                    properties:
                      header:
                        type: string
                      selectionType:
                        type: string
                        enum:
                        - single
                        - multi
                      sections:
                        type: array
                        items:
                          type: object
                          required:
                          - selectionValue
                          properties:
                            title:
                              type: string
                            selectionValue:
                              type: string
                              description: The postback value when calling the corresponding acknowledge endpoint.
                              example: signature
                            body:
                              type: string
                  caseDataId:
                    type: string
                    description: Returned only if `alreadyAck` is true.
                    format: uuid
                  signature:
                    type: string
                    description: Returned only if `alreadyAck` is true. For candidates who onboarded using KarmaCheck's onboarding experience, this is the value that the candidate entered into the signature input field on the legal step, which might not be exactly the same as the name that the case was ordered under.
              examples:
                Example 1:
                  value:
                    alreadyAck: false
                    title: <div>Canada Disclosure Acknowledgment and Authorization for Background Check</div>
                    header: <div>Disclosure regarding background investigation and investigative consumer reports, a summary of your rights under the Fair Credit Reporting Act</div>
                    body: <div><p><span>I acknowledge receipt of the separate documents entitled DISCLOSURE REGARDING BACKGROUND INVESTIGATION, A SUMMARY OF YOUR RIGHTS UNDER THE FAIR CREDIT REPORTING ACT and the DISCLOSURE FOR INVESTIGATIVE CONSUMER REPORT and certify that I have read and understand those documents. </span></p><p><span>In connection with your employment application with Example Company (the “Company”), this notice is intended to inform you that a consumer report(s) (also known as “a background check”) may be obtained on you from a consumer reporting agency for employment purposes. The reports may contain information about you relating to your criminal information or history, driving and/or motor vehicle records, education and/or employment history, social media, or other background checks, inclusive of but not necessarily limited to records and information from </span><span>any law enforcement agency, administrator, state or federal agency, institution, school or university (public or private), information service bureau, employer, or insurance company</span><span>. </span><span>I agree that a facsimile (&quot;fax&quot;), electronic or photographic copy of this Authorization shall be as valid as the original.</span></p><p><span>The report(s) is being prepared by our background screening vendor, KarmaCheck, Inc. and its associated partners or vendors.</span></p><p><span>The scope of this notice and below authorization is not limited to the present and, if you are hired, will continue throughout the course of your employment and allow the Company to conduct future screenings for retention, promotion or reassignment, as permitted by law and unless revoked by you in writing.</span></p></div>
                    authorizationStatement: '<div><p><b><u><span>AUTHORIZATION</span></u></b></p><p>By signing below, you authorize the obtaining of a consumer report by the Company at any time after receipt of this authorization and throughout the course of your employment, as described above.</p><form><p><input type=''checkbox'' readonly='''' ##SEND_REPORT## style=''-fs-checkbox-style: check;'' /><label>Check the box if you would like to receive a copyÏ of the investigative consumer report, free of charge, if one is obtained by the Company.</label></p><p>Signature</p><p><input type=''text'' readonly='''' value=''''/></p></form></div>'
                    authorizationObject:
                      sections:
                      - title: AUTHORIZATION
                        selectionValue: signature
                        body: By signing below, you authorize the obtaining of a consumer report by the Company at any time after receipt of this authorization and throughout the course of your employment, as described above.
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case does not have the specified disclosure as a requirement.
        '500':
          description: Internal Server Error
  /case/id/{caseId}/customdisclosure/{language}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of a case.
    - $ref: '#/components/parameters/language'
    post:
      tags:
      - Candidate onboarding
      summary: Acknowledge Custom Disclosure
      description: Submits acknowledgement of a Custom Disclosure document for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosure.
      operationId: post-case-id-caseId-customdisclosure-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalAcknowledgmentDisclosure'
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case doesn't have the specified disclosure service, or the candidate already acknowledged it.
        '500':
          description: Internal Server Error
    get:
      tags:
      - Candidate onboarding
      summary: Get Custom Disclosure
      description: Retrieves a Custom Disclosure document to present to the candidate so that the candidate can acknowledge and continue the onboarding process. If the candidate has already acknowledged the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details of the previous acknowledgement can be retrieved. This can also be used to determine whether the candidate can skip this specific disclosure step if they leave and then continue their onboarding later or on another device, for example.
      operationId: get-case-id-caseId-customdisclosure-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - alreadyAck
                - title
                - body
                - authorizationStatement
                - authorizationObject
                properties:
                  alreadyAck:
                    type: boolean
                    description: True if the candidate already acknowledged the disclosure; false otherwise.
                  title:
                    type: string
                    description: Escaped HTML.
                  header:
                    type: string
                    description: Escaped HTML.
                  body:
                    type: string
                    description: Escaped HTML.
                  authorizationStatement:
                    type: string
                    description: Escaped HTML.
                  authorizationObject:
                    type: object
                    required:
                    - sections
                    properties:
                      header:
                        type: string
                      selectionType:
                        type: string
                        enum:
                        - single
                        - multi
                      sections:
                        type: array
                        items:
                          type: object
                          required:
                          - selectionValue
                          properties:
                            title:
                              type: string
                            selectionValue:
                              type: string
                              description: The postback value when calling the corresponding acknowledge endpoint.
                              example: signature
                            body:
                              type: string
                  caseDataId:
                    type: string
                    description: Returned only if `alreadyAck` is true.
                    format: uuid
                  signature:
                    type: string
                    description: Returned only if `alreadyAck` is true. For candidates who onboarded using KarmaCheck's onboarding experience, this is the value that the candidate entered into the signature input field on the legal step, which might not be exactly the same as the name that the case was ordered under.
              examples:
                Example 1:
                  value:
                    alreadyAck: false
                    title: <div>Custom Disclosure Acknowledgment and Authorization for Background Check (custom)</div>
                    header: <div>Disclosure regarding background investigation and investigative consumer reports, a summary of your rights under the Fair Credit Reporting Act</div>
                    body: <div><p><span>custom disclosure - I acknowledge receipt of the separate documents entitled DISCLOSURE REGARDING BACKGROUND INVESTIGATION, A SUMMARY OF YOUR RIGHTS UNDER THE FAIR CREDIT REPORTING ACT and the DISCLOSURE FOR INVESTIGATIVE CONSUMER REPORT and certify that I have read and understand those documents. </span></p><p><span>In connection with your employment application with Example Company (the “Company”), this notice is intended to inform you that a consumer report(s) (also known as “a background check”) may be obtained on you from a consumer reporting agency for employment purposes. The reports may contain information about you relating to your criminal information or history, driving and/or motor vehicle records, education and/or employment history, social media, or other background checks, inclusive of but not necessarily limited to records and information from </span><span>any law enforcement agency, administrator, state or federal agency, institution, school or university (public or private), information service bureau, employer, or insurance company</span><span>. </span><span>I agree that a facsimile (&quot;fax&quot;), electronic or photographic copy of this Authorization shall be as valid as the original.</span></p><p><span>The report(s) is being prepared by our background screening vendor, KarmaCheck, Inc. and its associated partners or vendors.</span></p><p><span>The scope of this notice and below authorization is not limited to the present and, if you are hired, will continue throughout the course of your employment and allow the Company to conduct future screenings for retention, promotion or reassignment, as permitted by law and unless revoked by you in writing.</span></p></div>
                    authorizationStatement: '<div><p><b><u><span>AUTHORIZATION</span></u></b></p><p>By signing below, you authorize the obtaining of a consumer report by the Company at any time after receipt of this authorization and throughout the course of your employment, as described above.</p><form><p><input type=''checkbox'' readonly='''' ##SEND_REPORT## style=''-fs-checkbox-style: check;'' /><label>Check the box if you would like to receive a copyÏ of the investigative consumer report, free of charge, if one is obtained by the Company.</label></p><p>Signature</p><p><input type=''text'' readonly='''' value=''''/></p></form></div>'
                    authorizationObject:
                      sections:
                      - title: AUTHORIZATION
                        selectionValue: signature
                        body: By signing below, you authorize the obtaining of a consumer report by the Company at any time after receipt of this authorization and throughout the course of your employment, as described above.
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case does not have the specified disclosure as a requirement.
        '500':
          description: Internal Server Error
  /case/id/{caseId}/esig/{language}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of the case.
    - $ref: '#/components/parameters/language'
    post:
      tags:
      - Candidate onboarding
      summary: Acknowledge E-Signature
      description: Submits acknowledgement of the e-Signature for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a PDF file of the e-Signature document, which includes the candidate's acknowledgment and is available for download.
      operationId: post-case-id-caseId-esig-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalAcknowledgmentSignature'
            examples:
              Example 1:
                value:
                  signatureType: electronic
                  signature: John Hancock
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case doesn't include the e-Signature service, or the candidate already acknowledged it.
        '500':
          description: Internal Server Error
    get:
      tags:
      - Candidate onboarding
      summary: Get E-Signature
      description: 'Retrieves an e-Signature consent document and form that can be presented to and acknowledged by the candidate as part of the onboarding process. If the candidate has already acknowledged it, the response will indicate this as well as provide the `caseDataId` of the acknowledgement, which can be used to retrieve details. These can be used to determine whether the candidate can skip this step if they leave and then continue their onboarding later or on another device, for example.


        The e-Signature document can be customized. If a customer-specific version doesn''t exist, a default one will be returned.'
      operationId: get-case-id-caseId-esig-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - alreadyAck
                - title
                - body
                - authorizationStatement
                - authorizationObject
                properties:
                  alreadyAck:
                    type: boolean
                    description: True if the candidate already acknowledged the e-Signature document; false otherwise.
                  title:
                    type: string
                    description: Escaped HTML.
                  header:
                    type: string
                    description: Escaped HTML.
                  body:
                    type: string
                    description: Escaped HTML.
                  authorizationStatement:
                    type: string
                    description: Escaped HTML.
                  authorizationObject:
                    type: object
                    required:
                    - sections
                    properties:
                      header:
                        type: string
                      selectionType:
                        enum:
                        - single
                        - multi
                      sections:
                        type: array
                        items:
                          type: object
                          required:
                          - selectionValue
                          properties:
                            title:
                              type: string
                            selectionValue:
                              type: string
                              description: The value used when [acknowledging the e-Signature](karma-api-openapi.yaml/paths/~1case~1id~1{caseId}~1esig~1{language}/post).
                              enum:
                              - electronic
                              - manual
                            body:
                              type: string
                  caseDataId:
                    type: string
                    description: Returned only if `alreadyAck` is true.
                    format: uuid
                  signatureType:
                    description: Returned only if `alreadyAck` is true.
                    enum:
                    - electronic
                    - manual
                  signature:
                    type: string
                    description: Returned only if `alreadyAck` is true. For candidates who onboarded using KarmaCheck's onboarding experience, this is the value that the candidate entered into the signature input field on the legal step, which might not be exactly the same as the name that the case was ordered under.
              examples:
                Example 1:
                  value:
                    alreadyAck: false
                    title: <div>Electronic Signature Consent</div>
                    body: <p>e-signature - As part of the selection process at KarmaCheck, the &quot;Company,&quot; you will need to consent to a background check electronically. By typing your name and clicking in the box below, you are consenting to receive any communications (legally required or otherwise) and all changes to such communications electronically. In order to use the website, you must provide at your own expense an Internet connected device that is compatible with the minimum requirements outlined below. You also confirm that your device will meet these specifications and requirements and will permit you to access and retain the communications electronically each time you access and use the website.</p><p><b>System Requirements to Access Information</b></p><p>To receive and view an electronic copy of the Communications you must have the following equipment and software:</p><ul><li>A personal computer or other device which is capable of accessing the Internet. Your access to this page verifies that your system/device meets these requirements.</li><li>A current version of Chrome, Firefox, or Safari, Internet web browser which supports security industry best practices for HTTPS encrypted communications, JavaScript, and cookies. Your access to this page verifies that your browser meets these requirements.</li></ul><p><b>System Requirements to Retain Information</b></p><p>To retain a copy, you must either have a printer connected to your personal computer or other device or, alternatively, the ability to save a copy through use of printing service or software such as Adobe Acrobat®. If you would like to proceed using paper forms, please choose option 2 below.</p><p><b>Withdrawal of Electronic Acceptance of Disclosures and Notices</b></p><p>You can also contact us to withdraw your consent to receive any future communications electronically, including if the system requirements described above change and you no longer possess the required system. If you withdraw your consent, we will terminate your use of the KarmaCheck, Inc. website and the services provided through the KarmaCheck, Inc. website.</p><p>To ensure that a signature is unique and to safeguard you against unauthorized use of your name, your IP address 130.176.213.149 has been recorded and will be stored along with your electronic signature. Please note that if you wish to submit your Disclosure and Authorization Forms electronically, KarmaCheck, Inc. requires that you include your social security number or user identification. All of your information will be encrypted and transmitted via our secure website.</p>
                    authorizationStatement: '<form><h3>CHOOSE ONE OF THE FOLLOWING OPTIONS:</h3><h4><label for=''signatureTypeElectronic''>Option #1 - Electronic Signature</label></h4><input type=''radio''  id=''signatureTypeElectronic'' name=''signatureType'' value=''electronic''/><label for=''signatureTypeElectronic''>I, <input type=''text'' readonly='''' id=''electronicName'' name=''electronicName'' value=''''/><span>(type full name)</span>, consent to transacting electronically, including receiving legally required notices electronically. I understand that KarmaCheck, Inc. uses computer technology to ensure that my signed documents are not altered after submission. I agree to allow KarmaCheck, Inc. to validate my signed documents in this way.</label><h4><label for=''signatureTypeManual''>Option #2 - Manual Signature (will delay your start date)</label></h4><input type=''radio''  id=''signatureTypeManual'' name=''signatureType'' value=''manual''/><label for=''signatureTypeManual''>I, <input type=''text'' readonly='''' id=''manualName'' name=''manualName'' value=''''/><span>(type full name)</span>, <em><strong>do not</strong></em> wish to electronically sign my documents. I will print out and sign paper documents and return them to the Company. I understand this will delay the selection process.</label></form>'
                    authorizationObject:
                      header: 'CHOOSE ONE OF THE FOLLOWING OPTIONS:'
                      selectionType: single
                      sections:
                      - title: 'Option #1 - Electronic Signature'
                        selectionValue: electronic
                        body: I consent to transacting electronically, including receiving legally required notices electronically. I understand that KarmaCheck, Inc. uses computer technology to ensure that my signed documents are not altered after submission. I agree to allow KarmaCheck, Inc. to validate my signed documents in this way.
                      - title: 'Option #2 - Manual Signature (will delay your start date)'
                        selectionValue: manual
                        body: I <em><strong>do not</strong></em> wish to electronically sign my documents. I will print out and sign paper documents and return them to the Company. I understand this will delay the selection process.
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case does not have e-Signature as a requirement.
        '500':
          description: Internal Server Error
  /case/id/{caseId}/fcra/{language}:
    parameters:
    - schema:
        type: string
      name: caseId
      in: path
      required: true
      description: The ID of a case.
    - $ref: '#/components/parameters/language'
    post:
      tags:
      - Candidate onboarding
      summary: Acknowledge FCRA
      description: Submits acknowledgement of the FCRA for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged FCRA document.
      operationId: post-case-id-caseId-fcra-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: The case was not found.
        '422':
          description: The case doesn't include the FCRA service, or the candidate already acknowledged it.
        '500':
          description: Internal Server Error
    get:
      tags:
      - Candidate onboarding
      summary: Get FCRA
      description: 'Retrieves a Fair Credit Reporting Act (FCRA) consent document and form that can be presented to and acknowledged by the candidate as part of the onboarding process. If the candidate has already acknowledged it, the response will indicate this as well as provide the `caseDataId` of the acknowledgement, which can be used to retrieve details. These can be used to determine whether the candidate can skip this step if they leave and then continue their onboarding later or on another device, for example.


        The FCRA document can be customized. If a customer-specific version doesn''t exist, a default one will be returned.'
      operationId: get-case-id-caseId-fcra-language
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
        description: The language code (e.g. en-US)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - alreadyAck
                - title
                - body
                - authorizationStatement
                - authorizationObject
                properties:
                  alreadyAck:
                    type: boolean
                    description: True if the candidate already acknowledged the FCRA document; false otherwise.
                  title:
                    type: string
                    description: Escaped HTML.
                  header:
                    type: string
                    description: Escaped HTML.
                  body:
                    type: string
                    description: Escaped HTML.
                  authorizationStatement:
                    type: string
                    description: Escaped HTML.
                  authorizationObject:
                    type: object
                    required:
                    - sections
                    properties:
                      header:
                        type: string
                      selectionType:
                        type: string
                        enum:
                        - single
                        - multi
                      sections:
                        type: array
                        items:
                          type: object
                          required:
                          - selectionValue
                          properties:
                            title:
                              type: string
                            selectionValue:
                              type: string
                              description: The postback value when acknowledging the FCRA document.
                              example: 'true'
                            body:
                              type: string
                  caseDataId:
                    type: string
                    description: Returned only if `alreadyAck` is true.
                    format: uuid
              examples:
                Example 1:
                  value:
                    alreadyAck: false
                    title: <div>FCRA Summary of Rights</div>
                    header: '<div><p><small><b><i>Para información en español, visite  <a target

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