> ## Documentation Index
> Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create testimony for case

> Stores personally identifiable information (PII) on a candidate in KarmaCheck. Only one piece of PII can be included in a single piece of testimony.

Testimony is owned by the candidate, and can be attached to a case. When testimony is attached to a case, a separate case testimony record is created, which then becomes part of the case.



## OpenAPI

````yaml /background-check-api/api-reference/openapi.json post /testimony/create/case/id/{caseId}
openapi: 3.1.0
info:
  title: KarmaCheck 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: Authentication
  - name: Cases
  - name: Candidate onboarding
  - name: Secure documents
  - name: Packages
  - name: Services
  - name: Users
  - name: Companies
  - name: Partner integrations
paths:
  /testimony/create/case/id/{caseId}:
    parameters:
      - schema:
          type: string
        name: caseId
        in: path
        required: true
        description: The identifier of the case for which to create a testimony.
    post:
      tags:
        - Candidate onboarding
      summary: Create testimony for case
      description: >-
        Stores personally identifiable information (PII) on a candidate in
        KarmaCheck. Only one piece of PII can be included in a single piece of
        testimony.


        Testimony is owned by the candidate, and can be attached to a case. When
        testimony is attached to a case, a separate case testimony record is
        created, which then becomes part of the case.
      operationId: post-testimony-create-case-id-caseId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Testimony'
            examples:
              Education testimony:
                value:
                  testimonyTypeId: 19edb27e-5bfd-4c0f-888a-a5130b2f5250
                  details:
                    institution: UCLA
                    city: Los Angeles
                    state: CA
                    country: US
                    educationType: College/University
                    current: false
                    degree: B.S.
                    major: Nursing
                    monthBegin: September
                    yearBegin: '2015'
                    monthEnd: May
                    yearEnd: '2019'
              Professional License and Certification testimony:
                value:
                  testimonyTypeId: testimony-type-cplc
                  testimonySubType: 512d0d24-a4bd-4b1d-b6d1-182247a0f6ec
                  details:
                    cplcId: 512d0d24-a4bd-4b1d-b6d1-182247a0f6ec
                    fields:
                      - fieldId: certifyingBody
                        value: AMTA
                      - fieldId: licenseNumber
                        value: M123456
                      - fieldId: firstName
                        value: John
                      - fieldId: lastName
                        value: Smith
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    description: The unique identifier of the testimony created.
                    format: uuid
              examples:
                Example 1:
                  value:
                    id: e0c9c732-68ea-4f73-857d-d37f1c9e2028
        '403':
          description: Forbidden
        '422':
          description: The request data is invalid or incomplete.
        '500':
          description: Internal Server Error
components:
  schemas:
    Testimony:
      title: Testimony
      type: object
      required:
        - testimonyTypeId
      properties:
        testimonyTypeId:
          $ref: '#/components/schemas/TestimonyType'
          type: string
        testimonySubType:
          type: string
          description: >-
            Only required for Professional License and Certification testimony,
            for which you must provide the `cplcId` as the `testimonySubType`.
            For education testimony, this field must be provided as
            `no-testimony-to-verify` if the candidate has no education testimony
            to verify; this provides a form of candidate affirmation that they
            have no education history to verify. Simply leaving off any
            testimony records in such a scenario will require KarmaCheck
            Customer Success intervention and cause processing delays.
        description:
          type: string
          description: >-
            A free-form description of the testimony. If not provided, one will
            be automatically generated based on the type and details of the
            testimony.
        details:
          description: Shape of payload must correspond to the `testimonyTypeId`.
          oneOf:
            - $ref: '#/components/schemas/TestimonyEducationCreate'
            - $ref: '#/components/schemas/TestimonyEmploymentCreate'
            - $ref: '#/components/schemas/TestimonyDriversLicense'
            - $ref: '#/components/schemas/TestimonyParentalConsent'
            - $ref: '#/components/schemas/TestimonyAddress'
            - $ref: '#/components/schemas/TestimonyCustomProfessionalLicense'
          type: object
    TestimonyType:
      title: TestimonyType
      type: string
      enum:
        - 19edb27e-5bfd-4c0f-888a-a5130b2f5250
        - aa99dc08-0238-4050-9176-bf322e077f71
        - 3d83f3a0-fb6c-4c5a-a4dc-4dbf6a663870
        - 994bb728-f06d-4e4d-b689-f180adfb6ca5
        - 4143f0d4-4e3d-4ff7-b40a-9a26b569cf32
        - testimony-type-cplc
      description: |-
        The ID of the type of candidate data provided as testimony.

        - Education: `19edb27e-5bfd-4c0f-888a-a5130b2f5250`
        - Employment: `aa99dc08-0238-4050-9176-bf322e077f71`
        - Driver's License: `3d83f3a0-fb6c-4c5a-a4dc-4dbf6a663870`
        - Parental Consent: `994bb728-f06d-4e4d-b689-f180adfb6ca5`
        - Address: `4143f0d4-4e3d-4ff7-b40a-9a26b569cf32`
        - Professional License and Certification: `testimony-type-cplc`
    TestimonyEducationCreate:
      title: TestimonyEducation
      type: object
      description: >-
        The testimony details when `testimonyTypeId` is
        `19edb27e-5bfd-4c0f-888a-a5130b2f5250`. **Note:** Multiple properties
        are currently optional, but are strongly recommended to be included in
        requests.
      required:
        - institution
        - city
        - state
        - country
        - current
        - monthEnd
        - yearEnd
      properties:
        institution:
          type: string
          description: >-
            The name of the institution where the candidate received their
            education.
        city:
          type: string
          description: >-
            The city in which the institution is located. Recommended to be
            included in *all* requests.
        state:
          type: string
          description: >-
            The two-letter state code. Recommended to be included in *all*
            requests.
          example: NY
        country:
          type: string
          description: >-
            The ISO 3166 (2 or 3 letter) code. Recommended to be included in
            *all* requests.
          example: US
        nameIfDifferent:
          type: string
          description: The candidate's name that's on record with the institution.
        educationType:
          example: College/University
          description: >-
            The type of education, such as a college or university, a high
            school or equivalent (for example, GED), a technical or trade
            school, or other.
          type: string
        current:
          type: boolean
          default: false
          description: >-
            If true, the candidate is currently enrolled at the institution. If
            false, the candidate is not currently enrolled. (Required true if
            `monthEnd` and `yearEnd` are not provided)
        degree:
          type: string
          description: The educational degree.
        major:
          type: string
          description: The candidate's field of study.
        gpa:
          type: string
          description: The candidate's grade point average (GPA).
        monthBegin:
          type: string
          description: The month in which the candidate began their education.
        yearBegin:
          type: string
          description: The year in which the candidate began their education.
        monthEnd:
          type: string
          description: >-
            The month in which the candidate completed their education. Not
            applicable if `current` is true. (Required if `current` is false or
            not provided)
        yearEnd:
          type: string
          description: >-
            The year in which the candidate completed their education. Not
            applicable if `current` is true. (Required if `current` is false or
            not provided)
        comments:
          type: string
        contact:
          $ref: '#/components/schemas/TestimonyContact'
          description: The institution's contact information.
    TestimonyEmploymentCreate:
      title: TestimonyEmployment
      type: object
      description: >-
        The testimony details when `testimonyTypeId` is
        `aa99dc08-0238-4050-9176-bf322e077f71`. **Note:** Multiple properties
        are currently optional, but are strongly recommended to be included in
        requests.
      required:
        - employer
        - city
        - state
        - country
        - current
        - position
        - monthBegin
        - yearBegin
        - monthEnd
        - yearEnd
      properties:
        employer:
          type: string
          description: >-
            The name of the candidate's current or former employer. Must be less
            than or equal to 100 characters.
        city:
          type: string
          description: >-
            The city of employment. Recommended to be included in *all*
            requests.
        state:
          type: string
          description: >-
            The two-letter state code. Recommended to be included in *all*
            requests.
        country:
          type: string
          description: >-
            The ISO 3166 (2 or 3 letter) code. Recommended to be included in
            *all* requests.
        nameIfDifferent:
          type: string
          description: The candidate's name that's on record with the employer.
        current:
          type: boolean
          description: >-
            If true, the candidate is currently employed with the employer. If
            false, the candidate is no longer employed with the employer.
            Recommended to be included in *all* requests. (Required true if
            `monthEnd` and `yearEnd` are not provided)
          default: false
        okToContact:
          type: boolean
          description: >-
            If true, the employer can be contacted about the candidate. If
            false, the employer cannot be contacted. Recommended to be included
            in *all* requests.
        position:
          type: string
          description: The candidate's position with the employer.
        incomeAmount:
          type: string
          description: >-
            The amount earned.  Recommended to be included for Employment Income
            Verification.
        incomeCurrency:
          type: string
          description: >-
            The currency of the income earned. This is applicable to Employment
            Income Verification.
        incomeFrequency:
          type: string
          description: >-
            The frequency of the amount earned. Recommended to be included for
            Employment Income Verification.
        monthBegin:
          type: string
          description: The month in which the candidate began their employment.
        yearBegin:
          type: string
          description: The year in which the candidate began their employment.
        monthEnd:
          type: string
          description: >-
            The month in which the candidate ended their employment. Not
            applicable if `current` is true. (Required if `current` is false or
            not provided)
        yearEnd:
          type: string
          description: >-
            The year in which the candidate ended their employment. Not
            applicable if `current` is true. (Required if `current` is false or
            not provided)
        additionalInfo:
          type: string
        contact:
          $ref: '#/components/schemas/TestimonyContact'
          description: The employer's contact information.
        staffingAgency:
          type: string
          description: >-
            The Staffing Agency that the candidate is working for the employer
            through.(If applicable)
          maxLength: 100
    TestimonyDriversLicense:
      title: TestimonyDriversLicense
      type: object
      required:
        - id
        - state
        - licenseNumber
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the testimony record.
          readOnly: true
        country:
          type: string
        state:
          type: string
        licenseNumber:
          type: string
          description: >-
            Must be a valid [state driver's license
            format](https://ntsi.com/drivers-license-format/).
        firstNameIfDifferent:
          type: string
        middleInitialIfDifferent:
          type: string
        lastNameIfDifferent:
          type: string
        source:
          type: string
          readOnly: true
    TestimonyParentalConsent:
      title: TestimonyParentalConsent
      type: object
      required:
        - id
        - parentGivenName
        - parentFamilyName
        - parentEmail
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the testimony record.
          readOnly: true
        parentGivenName:
          type: string
        parentFamilyName:
          type: string
        parentEmail:
          type: string
    TestimonyAddress:
      title: TestimonyAddress
      type: object
      required:
        - id
        - city
        - state
        - country
        - address
        - postalCode
        - current
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the testimony record.
          readOnly: true
        city:
          type: string
          maxLength: 30
        state:
          type: string
          description: For US, use 2-letter abbreviation
        country:
          type: string
          description: ISO 3166 (2 or 3 letter) code
        address:
          type: string
          maxLength: 60
        address2:
          type: string
        postalCode:
          type: string
        current:
          type: boolean
        source:
          type: string
          example: certn
          readOnly: true
    TestimonyCustomProfessionalLicense:
      title: TestimonyCustomProfessionalLicense
      type: object
      required:
        - id
        - caseDataIds
        - cplcId
        - cplcName
        - fields
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the testimony record.
          readOnly: true
        caseDataIds:
          type: array
          items:
            type: string
          readOnly: true
        cplcId:
          type: string
        cplcName:
          type: string
          readOnly: true
        fields:
          type: array
          items:
            type: object
            required:
              - fieldId
              - value
            properties:
              fieldId:
                type: string
              value:
                type: string
    TestimonyContact:
      title: TestimonyContact
      type: object
      properties:
        phone:
          type: string
        email:
          type: string
        website:
          type: string
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````