Testimony

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/karmacheck/json-schema/karmacheck-testimony-schema.json",
  "title": "Testimony",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/karmacheck-candidate-onboarding-api-openapi.yml#/components/schemas/Testimony",
  "type": "object",
  "required": [
    "testimonyTypeId"
  ],
  "properties": {
    "testimonyTypeId": {
      "$ref": "#/$defs/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": "#/$defs/TestimonyEducationCreate"
        },
        {
          "$ref": "#/$defs/TestimonyEmploymentCreate"
        },
        {
          "$ref": "#/$defs/TestimonyDriversLicense"
        },
        {
          "$ref": "#/$defs/TestimonyParentalConsent"
        },
        {
          "$ref": "#/$defs/TestimonyAddress"
        },
        {
          "$ref": "#/$defs/TestimonyCustomProfessionalLicense"
        }
      ],
      "type": "object"
    }
  },
  "$defs": {
    "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",
          "readOnly": true
        }
      }
    },
    "TestimonyContact": {
      "title": "TestimonyContact",
      "type": "object",
      "properties": {
        "phone": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "website": {
          "type": "string"
        }
      }
    },
    "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"
              }
            }
          }
        }
      }
    },
    "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
        }
      }
    },
    "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."
        },
        "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 institution."
        },
        "educationType": {
          "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": "#/$defs/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": "#/$defs/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
        }
      }
    },
    "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"
        }
      }
    },
    "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.\n\n- Education: `19edb27e-5bfd-4c0f-888a-a5130b2f5250`\n- Employment: `aa99dc08-0238-4050-9176-bf322e077f71`\n- Driver's License: `3d83f3a0-fb6c-4c5a-a4dc-4dbf6a663870`\n- Parental Consent: `994bb728-f06d-4e4d-b689-f180adfb6ca5`\n- Address: `4143f0d4-4e3d-4ff7-b40a-9a26b569cf32`\n- Professional License and Certification: `testimony-type-cplc`"
    }
  }
}