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': description: 'The response can include any combination of the objects described below. The structure of the response is determined by: - Any points of contact that were added to the case. - All screenings from the package that was used to create the case, regardless of whether those screenings were ordered for the case.' content: application/json: schema: $ref: '#/components/schemas/Configuration' examples: {} '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error /case/id/{caseId}/data/{serviceTypeId}: parameters: - schema: type: string name: caseId in: path description: The ID of the case to retrieve details for. required: true - schema: type: string enum: - 30bc2c03-c8dd-409a-8da6-e0070ea6a681 - a3b74b1b-b665-40be-bad2-2a49c801cf3f - service-type-payment - service-type-idv - service-type-shipment name: serviceTypeId in: path required: true description: The ID of the [service type](docs/reference/service-type.md) to retrieve. get: tags: - Cases summary: Get case data by case ID description: Gets the details associated with services ordered and processed for a case. operationId: get-case-id-caseid-data-servicetypeid responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array description: The case data associated with each service for the case. This will be undefined if no case data records exist for the given `serviceTypeId`. items: $ref: '#/components/schemas/CaseData' examples: Example 1: value: data: - id: 12345678-f4ae-4579-b43d-5ab19c93add0 description: National Criminal Search caseId: 1c233169-fc0c-474e-9311-a35029e6154b storageId: 1234fed4-e9a6-45fc-b280-8df5dac39c37 details: "{\n \"source\" : \"TazWorks\",\n \"rawDataType\" : \"xml\",\n \"rawDataKey\" : \"16a2841b-a9c2-4415-b57b-280ea1a6e4f9\",\n \"serviceId\" : \"d8e3dbdb-c2d7-4787-9736-86fffab74da4\",\n \"dateCompleted\" : \"2024-08-07T22:04:44.222+00:00\",\n \"timeToComplete\" : \"instant\",\n \"reportHtmlSecureDocumentId\" : \"fea58286-0283-452a-8151-3796435d0e44\"\n}" serviceId: d8e3dbdb-c2d7-4787-9736-86fffab74da4 serviceName: National Criminal Search serviceTypeId: 30bc2c03-c8dd-409a-8da6-e0070ea6a681 serviceTypeName: Screening statusId: e086eea7-e4b7-4c74-ac04-4c3b51c23a33 status: clear statusDisplayName: Clear crStamp: '2024-08-07T22:04:37.000+00:00' modStamp: '2024-08-07T22:04:42.000+00:00' groupProfileId: ab1234c5-ac27-4c96-bb22-06ae7e372fd2 candidateId: 123d5439-18fe-4f14-b7fb-00eca6aa598f detailsObject: source: TazWorks rawDataType: xml rawDataKey: 16a2841b-a9c2-4415-b57b-280ea1a6e4f9 serviceId: d8e3dbdb-c2d7-4787-9736-86fffab74da4 dateCompleted: '2024-06-28T16:08:36.222+00:00' timeToComplete: instant reportHtmlSecureDocumentId: fea58286-0283-452a-8151-3796435d0e44 serviceCategory: Criminal Check serviceCategoryId: service-cat-criminal locked: false - id: 66068dd2-2bdb-44c7-97c9-14bd92eeed7c description: NDOT Physical caseId: 4b473169-fc0c-474e-9311-a35029e6154b storageId: 637807a7-fd66-4ec4-853a-30cfc6a902d2 details: '{"dateCompleted":"2024-08-07T22:05:00.000Z","timeToComplete":"instant","effectiveDate":"2024-08-07T22:05:00.000Z","externalId":"tWSAxlkhueHHoWRPUzGU","confirmationNumber":"AItWSAxlkhueHHoWRPUzGU","scheduledDate":"2024-08-02T22:04:00.000Z","expirationDate":"2024-08-09T22:04:00.000Z","clientName":"Example Company","clientAccount":"629236","clientSubAccount":"28","clinicId":"9588","clinicName":"Test Clinic","clinicAddress1":"7500 W 110th Street","clinicAddress2":"","clinicCity":"Omaha","clinicState":"NE","clinicZip":"66210","clinicPhoneNumber":"800-555-0175","clinicFaxNumber":"8005550100","network":"Out of Network","firstName":"Alex","lastName":"Miller","birthDate":"06/21/1985","ssnLast4":"3333","serviceId":"service-ohs-ndotphysical","source":"escreen","rawDataType":"xml","rawDataKey":"escreen-tWSAxlkhueHHoWRPUzGU-ohs-779b7282-11fa-4fc0-826e-9b6d0cac94a2","physicalID":"658070","verificationType":"physical","componentId":"1","componentDescription":"Non-DOT Physical","status":"Complete","result":"Able to work without restrictions/limitations","resultId":"ohs-result-22-acknowleged-1","resultCode":"22","resultDate":"2024-08-07T22:05:00.000Z","resultDueToReason":"","resultExpirationDate":"","resultStatusDescription":"Pass","partialReasons":[],"examDate":"8/7/2024","followUpDate":"","certExpirationDate":"","tbReadDate":"","comments":"Alex Miller is clean","clientAddress1":"7878 Guy St","clientCity":"Omaha","clientContact":"Rosario S.","clientState":"NE","clientZip":"64086","collectionSitePhoneNumber":"800-555-0155","cdlFlag":"0","overallStatusDescription":"Complete","physicalReasonDescription":"Follow Up","additionalInfo":""}' serviceId: service-ohs-ndotphysical serviceName: NDOT Physical serviceTypeId: 30bc2c03-c8dd-409a-8da6-e0070ea6a681 serviceTypeName: Screening statusId: 1a8490cb-084d-4209-bf2f-d46e41d760d6 status: acknowledge statusDisplayName: Clear crStamp: '2024-08-07T22:04:38.000+00:00' modStamp: '2024-08-07T22:05:32.000+00:00' groupProfileId: ab1234c5-ac27-4c96-bb22-06ae7e372fd2 candidateId: 123d5439-18fe-4f14-b7fb-00eca6aa598f detailsObject: dateCompleted: '2024-08-07T22:05:00.000Z' timeToComplete: instant effectiveDate: '2024-08-07T22:05:00.000Z' externalId: tWSAxlkhueHHoWRPUzGU confirmationNumber: AItWSAxlkhueHHoWRPUzGU scheduledDate: '2024-08-02T22:04:00.000Z' expirationDate: '2024-08-09T22:04:00.000Z' clientName: Example Company clientAccount: '629236' clientSubAccount: '28' clinicId: '9588' clinicName: Test Clinic clinicAddress1: 7500 W 110th Street clinicAddress2: '' clinicCity: Omaha clinicState: NE clinicZip: '66210' clinicPhoneNumber: 800-555-0175 clinicFaxNumber: '8005550100' network: Out of Network firstName: Alex lastName: Miller birthDate: 06/21/1985 ssnLast4: '3333' serviceId: service-ohs-ndotphysical source: escreen rawDataType: xml rawDataKey: escreen-tWSAxlkhueHHoWRPUzGU-ohs-779b7282-11fa-4fc0-826e-9b6d0cac94a2 physicalID: '658070' verificationType: physical componentId: '1' componentDescription: Non-DOT Physical status: Complete result: Able to work without restrictions/limitations resultId: ohs-result-22-acknowleged-1 resultCode: '22' resultDate: '2024-08-07T22:05:00.000Z' resultDueToReason: '' resultExpirationDate: '' resultStatusDescription: Pass partialReasons: [] examDate: 8/7/2024 followUpDate: '' certExpirationDate: '' tbReadDate: '' comments: Alex Miller is clean clientAddress1: 7878 Guy St clientCity: Omaha clientContact: Rosario S. clientState: NE clientZip: '64086' collectionSitePhoneNumber: 800-555-0155800-555-0155 cdlFlag: '0' overallStatusDescription: Complete physicalReasonDescription: Follow Up additionalInfo: '' serviceCategory: Occupational Health Screening serviceCategoryId: service-cat-ohs serviceSubCategory: Physical serviceSubCategoryId: service-subcat-physical locked: false '403': description: Forbidden '500': description: Internal Server Error /case/id/{caseId}: parameters: - schema: type: string name: caseId in: path required: true get: tags: - Cases summary: Get case description: Retrieves the details of a case by its ID. The response includes summary-level information with IDs for accessing details using other endpoints. operationId: get-case-id-caseid 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 an invalid authentication token, valid authorization but insufficient permissions, or that the case ID provided was not found. '500': description: Internal Server Error security: - JWT: [] /case/id/{caseId}/report/pdf/download/url: parameters: - schema: type: string name: caseId in: path required: true description: The ID of the case to get a report for. post: tags: - Cases summary: Get custom report download URL description: Returns a URL to download a PDF report for one or more case screenings (in other words, case data). operationId: post-caseid-caseId-report-pdf-download-url requestBody: content: application/json: schema: x-examples: Example 1: caseDataIds: - 7fcb0b74-147b-48e2-84c9-7aefa3d0e0fa excludeCaseDataAttachments: false type: object required: - caseDataIds properties: caseDataIds: type: array description: The list of case screenings to include in the report. Each element of this array is the `caseDataId` associated with an ordered service. It is *not* the `serviceId` itself. This granularity allows you to generate a report with only some instances of an ordered service. For example, you can generate a report with just the most recent attempt at a Drug 10 Panel instead of a previous one that was lost in transit. items: type: string excludeCaseDataAttachments: type: boolean default: false description: Some services might have attachments that are permitted to appear in the PDF report, like search results or supporting documents. By default, these will appear in the report. You can explicitly specify whether to include these attachments, if there are any associated with the `caseDataId`s you've chosen, by providing this flag. If there are no applicable attachments, this flag is ignored. Note that some attachments visible in the dashboard, like eScreen ePassports, have feature flags that control whether or not they will show in the reports, even if you set this flag to `false`. Contact Customer Success if you do not see attachments that you are expecting to see. examples: Example 1: value: caseDataIds: - 7fcb0b74-147b-48e2-84c9-7aefa3d0e0fa excludeCaseDataAttachments: false description: '' responses: '200': description: The URL returned in this response is a self-signed S3 URL with a time to live (TTL) of 60 seconds. You have 60 seconds to begin the download, but once the download begins, it can take as long as needed. As many download attempts as needed can be made during the 60-second period. content: text/html: schema: type: string format: uri example: https://s3.amazonaws.com/stage.private.storage-bin.karmacheck.io/98704f90-2770-4999-ba01-453ef6d0deea-report.pdf?AWSAccessKeyId=REDACTED_AWS_ACCESS_KEY_ID&Expires=1699391676&Signature=sL5Am9sMbvWSd8%2B%2F5CoejqsmeO4%3D&X-Amzn-Trace-Id=Root%3D1-654aa880-4e319ca04da8fe7c3faa6d1e%3BParent%3D3b8e51107e55b256%3BSampled%3D0%3BLineage%3D1dda0c46%3A0&x-amz-security-token=FwoGZXIvYXdzEIb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDML%2B7WMBiIwah8j4aiK7AVB2sHfQ5tkVkU4Okov%2BRz%2BB%2FMSg6XpdmcOmEb5hJAdg%2BEAxL%2Bt33yt3We5CJUf4auHXMr9huYmkLK%2FQtg3QJQS8CAcZKXPSCaAQ7Wn66D8%2Bpl3x5ppxmgzAONgfejqSfKrYgxl0Srr%2BuAHOz53R5ujbAUA9wwgvfXFoWlJZ4YHah%2BgjFFLzbva%2F4a63g5Mw0Nyngb3EoccWRRn4tEWlzavuGjXYffFcZo2jHT7GXr9eeLoK1sZ96c2jn9oo6cqqqgYyLT8yXkspVciOKVnnBS32UCjIS5rlwu7bL2bMJAW2ocIW0ymnVbak0qb1fMnp6w%3D%3D '403': description: Your token does not have access to the `caseId` requested, or you do not have access to individual screening reports. '404': description: The report could not be found in the S3 bucket. '422': description: 'A data issue exists, or the report is not ready. In particular, custom reports require that all `caseDataId`s requested for the report have their services in a completed state. If one or more services are pending, a 422 will be returned.' '500': description: Internal Server Error get: tags: - Cases summary: Get full report download URL description: Returns a URL to download a PDF report for the entire case and available attachments. operationId: get-caseid-caseId-report-pdf-download-url responses: '200': description: The URL returned in this response is a self-signed S3 URL with a time to live (TTL) of 60 seconds. You have 60 seconds to begin the download, but once the download begins, it can take as long as needed. As many download attempts as needed can be made during the 60-second period. content: text/html: schema: type: string format: uri example: https://s3.amazonaws.com/stage.private.storage-bin.karmacheck.io/98704f90-2770-4999-ba01-453ef6d0deea-report.pdf?AWSAccessKeyId=REDACTED_AWS_ACCESS_KEY_ID&Expires=1699391676&Signature=sL5Am9sMbvWSd8%2B%2F5CoejqsmeO4%3D&X-Amzn-Trace-Id=Root%3D1-654aa880-4e319ca04da8fe7c3faa6d1e%3BParent%3D3b8e51107e55b256%3BSampled%3D0%3BLineage%3D1dda0c46%3A0&x-amz-security-token=FwoGZXIvYXdzEIb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDML%2B7WMBiIwah8j4aiK7AVB2sHfQ5tkVkU4Okov%2BRz%2BB%2FMSg6XpdmcOmEb5hJAdg%2BEAxL%2Bt33yt3We5CJUf4auHXMr9huYmkLK%2FQtg3QJQS8CAcZKXPSCaAQ7Wn66D8%2Bpl3x5ppxmgzAONgfejqSfKrYgxl0Srr%2BuAHOz53R5ujbAUA9wwgvfXFoWlJZ4YHah%2BgjFFLzbva%2F4a63g5Mw0Nyngb3EoccWRRn4tEWlzavuGjXYffFcZo2jHT7GXr9eeLoK1sZ96c2jn9oo6cqqqgYyLT8yXkspVciOKVnnBS32UCjIS5rlwu7bL2bMJAW2ocIW0ymnVbak0qb1fMnp6w%3D%3D '403': description: Your token does not have access to the `caseId` requested, or the case is still in a status of pending and you do not have access to reports for cases that are still pending. '404': description: The report could not be found in the S3 bucket. '422': description: A data issue exists, or the report is not ready. '500': description: Internal Server Error /case/id/{caseId}/data/{serviceId}/pdf: 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: Get legal doc for case data description: Returns inline 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 responses: '200': description: OK '403': description: Forbidden '404': description: Not Found '422': description: The document is not ready. '500': description: Internal Server Error security: - JWT: [] /case/id/{caseId}/preadverse/{type}/pdf: 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: Get pre-adverse action document description: Returns inline 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 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: [] /case/id/{caseId}/services/{serviceType}: parameters: - schema: type: string name: caseId in: path required: true - schema: type: string enum: - screenings - payment - idv - legal - shipment name: serviceType in: path required: true description: The type of services to retrieve in the response. If an undefined value is provided, only screenings are returned. get: tags: - Cases summary: Get services for case description: 'Retrieves a list of services ordered for a case. The list includes services of only one of the following types: - **`idv`:** Identity verification services ordered for the case. - **`legal`:** Legal checks ordered for the case. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures). - **`payment`:** Payment services ordered for the case. - **`screenings`:** Screenings ordered for the case. - **`shipment`:** Shipments ordered for the case.' operationId: get-case-id-caseId-services-serviceType responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ServiceGroupServicesCase' '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error /case/id/{caseId}/action/place: parameters: - schema: type: string name: caseId in: path required: true description: The ID of the case to place. put: tags: - Cases summary: Place case description: Sets the status of a case to Placed in the system. Internally, the API sets the case's status to `Adjudicated` and its result to `Placed`. The secondary status, if any, gets reset. operationId: put-case-id-caseId-action-place parameters: [] responses: '200': description: OK '403': description: Forbidden '404': description: The `caseId` provided was not found. '422': description: The case could not be put into Placed. This is likely because the case is not ready to be placed. '500': description: Internal Server Error /case/id/{caseId}/action/preadverse: parameters: - schema: type: string name: caseId in: path required: true description: The ID of the case to to begin an adverse action process on. post: tags: - Cases summary: Pre-adverse action for case description: Begins the adverse action process for a case by putting the case into the Pre-Adverse Action status. This also sends a pre-adverse action notice to the candidate by email, which can also be downloaded from both the customer and candidate dashboards. operationId: post-case-id-caseId-action-preadverse requestBody: content: application/json: schema: type: object x-examples: Example 1: reason: The candidate was positive for cocaine in his drug test. adverseScreeningSelections: - service-drug-1200-panel properties: reason: type: string description: An explanation of why the adverse action process is being initiated for the case. adverseScreeningSelections: type: array description: A list of specific `serviceId`s whose results give some basis to begin the adverse action process for the case. items: type: string examples: Example 1: value: reason: The candidate was positive for cocaine in his drug test. adverseScreeningSelections: - service-drug-1200-panel description: The request body is optional, but if provided, note that the values in the `reason` and `adverseScreeningSelections` fields will be visible to the candidate in the pre-adverse action notice. This is to give an indication of the reason and specific screenings for which the action is being taken. responses: '200': description: OK '403': description: This response indicates that you don't have an authentication token, that you have insufficient permissions, or that the `caseId` provided was not found. '404': description: The `caseId` provided was not found. '422': description: This response indicates that the case cannot be put into Pre-Adverse Action. This is likely because the case is not in a complete state (which would require that all screenings have gone into some kind of complete status, whether clear or with records found). '500': description: Internal Server Error /case/unarchive/{caseId}: parameters: - schema: type: string name: caseId in: path required: true description: The ID of the case to unarchive. post: tags: - Cases summary: Unarchive case description: Unarchives a case so that it reappears in the KarmaCheck dashboard. This operation reverses a previous archive operation on the case. operationId: post-case-unarchive-caseId parameters: - schema: type: string name: caseId in: path required: true responses: '200': description: OK '403': description: Unauthorized Request '422': description: Could not unarchive case. '500': description: Server Error security: - JWT: [] components: schemas: DetailsFederalCriminal: title: DetailsFederalCriminal type: object description: Details from a federal criminal search. examples: - serviceId: fa226cb7-1214-4cdf-9296-6120a7376926 dateCompleted: '2024-08-14T14:34:17.741+00:00' timeToComplete: 2 days records: - state: PENNSYLVANIA county: PENNSYLVANIA EASTERN charge: 'Citation: 12.2345 M / Jaywalking' offenseType: Misdemeanor disposition: Guilty dispositionDate: '2019-06-02' caseNumber: 00230-FHB-123456 jurisdiction: PENNSYLVANIA EASTERN fileDate: '2019-06-02' contextualData: county=PENNSYLVANIA EASTERN jurisdiction=PENNSYLVANIA EASTERN properties: serviceId: type: string enum: - ee774b82-a411-4e2b-a38f-c0641bd836e7 dateCompleted: type: string format: date-time example: '2024-05-17T19:47:14.885+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string records: type: array description: Records found from the criminal search. items: type: object properties: state: type: string description: Not applicable to federal district searches. example: PENNSYLVANIA county: type: string description: Applicable to federal district searches. example: PENNSYLVANIA EASTERN charge: type: string example: 'Citation: 12.2345 M / Jaywalking' offenseType: type: string example: Misdemeanor disposition: type: string example: Guilty dispositionDate: type: string format: date example: '2019-06-22' caseNumber: type: string example: 00230-FHB-123456 comments: type: string jurisdiction: type: string example: PENNSYLVANIA EASTERN fileDate: type: string format: date example: '2019-06-22' contextualData: type: string CaseOrderDataDOB: title: CaseOrderDataDOB type: object description: The candidate data when `caseOrderDataTypeId` is `codt-dob`. required: - dob properties: dob: type: string example: '1986-06-26' format: date description: The candidate's date of birth in the format *YYYY*-*MM*-*DD*. ServiceGroupServicesAll: title: ServiceGroupServicesAll type: object examples: - serviceGroupServices: - serviceGroupId: 8afb91ff-7958-4f42-90e1-9bfed7db9bbf serviceGroupName: Basic Check 2023-04-13T20:51:49.938Z serviceGroupPrice: 1337 serviceGroupDescription: Common services for a basic background check serviceId: 03635d39-c9df-418f-948d-10d38a7e06db serviceName: National Sex Offender Search Alt serviceDescription: Search for candidate sex offender history serviceTypeId: 30bc2c03-c8dd-409a-8da6-e0070ea6a681 serviceTypeName: Screening serviceGroupEnabled: true serviceEnabled: true serviceAutoProcessEnabled: true serviceTypeEnabled: true serviceCategory: Criminal Check serviceCategoryId: service-cat-criminal conditional: false defaultSelected: false enabled: true serviceGroupServicesId: d2ff35ec-4da4-4a82-bb72-80980fc658ff required: - serviceGroupServices properties: serviceGroupServices: type: array description: A list of services, each containing detailed information about a service. items: type: object required: - serviceGroupId - serviceGroupName - serviceGroupDescription - serviceId - serviceName - serviceDescription - serviceTypeId - serviceTypeName - serviceGroupEnabled - serviceEnabled - serviceAutoProcessEnabled - serviceTypeEnabled - conditional - defaultSelected - enabled - serviceGroupServicesId properties: serviceGroupId: type: string serviceGroupName: type: string serviceGroupPrice: type: number description: The price of the package in United States cents. This is the price that candidates will pay via Stripe during onboarding to begin their check. Customers can request that a price be set on a package to pass on some or all of the price of the check to the candidate. serviceGroupDescription: type: string serviceId: type: string description: The unique ID of the service. See [Service](docs/reference/service.md) for a list of possible services. serviceName: type: string description: The name of the service. serviceDescription: type: string serviceTypeId: $ref: '#/components/schemas/ServiceTypeId' serviceTypeName: $ref: '#/components/schemas/ServiceTypeName' serviceSubTypeId: type: string enum: - jurisdiction-nationwide - jurisdiction-district - jurisdiction-statewide description: The ID of the subtype for the service. This is applicable only when `serviceId` is `ee774b82-a411-4e2b-a38f-c0641bd836e7` (Federal Criminal Search). serviceSubTypeName: type: string enum: - Nationwide - District - Statewide description: The service subtype. serviceGroupEnabled: type: boolean serviceEnabled: type: boolean serviceAutoProcessEnabled: type: boolean description: True if the service is available for a case that's ordered using the PII entry flow. False if the service is unavailable when using the PII entry flow. serviceTypeEnabled: type: boolean serviceCategory: $ref: '#/components/schemas/ServiceCategory' serviceCategoryId: $ref: '#/components/schemas/ServiceCategoryId' serviceSubCategory: $ref: '#/components/schemas/ServiceSubCategory' serviceSubCategoryId: $ref: '#/components/schemas/ServiceSubCategoryId' conditional: type: boolean description: True if the service is available only when adding to an order; false otherwise. A conditional service indicates that another service needs to run before this service can run. defaultSelected: type: boolean description: True if the service is selected by default when a dashboard user selects the package for a case; false otherwise. enabled: type: boolean description: True if the service is enabled for the package; false otherwise. serviceGroupServicesId: type: string DetailsCountyCriminal: type: object examples: - jurisdictions: - alias: JONES, STEPHEN jurisdiction: NY-NYOCA status: f657c777-c38d-489b-ac26-dd9bf0a88724 - alias: JONES, STEPHEN jurisdiction: NJ-ESSEX status: 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 records: - comments: null caseNumber: 502008CF012155YXYXMB jurisdiction: NY-NYOCA fileDate: '2019-07-10' charge: 1. Possession Of Schedule 4 Substance offenseType: Felony disposition: Pre Trial Intervention dispositionDate: '2019-08-01' nameOnRecord: JONES, STEPHEN state: NY county: NYOCA contextualData: state=NY county=NYOCA jurisdiction=NY-NYOCA - comments: null caseNumber: 502008CF012155YXYXMB jurisdiction: NY-NYOCA fileDate: '2019-07-10' charge: 2. Possession Of Schedule 2 Substance offenseType: Felony disposition: Pre Trial Intervention dispositionDate: '2019-08-01' nameOnRecord: JONES, STEPHEN state: NY county: NYOCA contextualData: state=NY county=NYOCA jurisdiction=NY-NYOCA - comments: null caseNumber: 502008CF012155YXYXMB jurisdiction: NY-NYOCA fileDate: '2019-07-10' charge: 3. Attempt To Obtain Controlled Substance By Fraud offenseType: Felony disposition: Pre Trial Intervention dispositionDate: '2019-08-01' nameOnRecord: JONES, STEPHEN state: NY county: NYOCA contextualData: state=NY county=NYOCA jurisdiction=NY-NYOCA description: Details from a county criminal search. title: DetailsCountyCriminal properties: jurisdictions: type: array description: Details about each jurisdictional search. items: type: object properties: alias: type: string description: The alias used in the search. example: JONES, STEPHEN jurisdiction: type: string description: The jurisdiction that was searched. records: type: array description: Records found from the jurisdictional search. items: type: object properties: comments: type: string caseNumber: type: string example: 123456CF012155YXYXMB jurisdiction: type: string example: NJ-ESSEX fileDate: type: string format: date example: '2019-07-10' charge: type: string example: 1. Unregistered Motor Vehicle offenseType: type: string example: Traffic disposition: type: string example: Nolle Prosse dispositionDate: type: string format: date example: '2019-08-01' nameOnRecord: type: string example: JONES, STEPHEN state: type: string example: NJ county: type: string example: ESSEX contextualData: type: string status: $ref: '#/components/schemas/CaseDataStatusID' description: "The status ID of the jurisdictional search.\n\n- acknowledge (done positive): 1a8490cb-084d-4209-bf2f-d46e41d760d6\n- clear (done and good): e086eea7-e4b7-4c74-ac04-4c3b51c23a33\n- consider (done and needs review): f657c777-c38d-489b-ac26-dd9bf0a88724 \n- not_found (unable to verify): 96e0420a-4396-4bd1-9b54-447f00eb3ed8\n- canceled (not performed): 3d726502-d2e2-4d10-859b-8a218f22086d\n- complete (done without prejudice): case-data-status-complete\n- pending (in progress): 8f29e0de-10f2-4c84-8379-16c6eb7cdf64\n- error (error during processing): case-data-status-error" modifiedDate: type: string format: date-time example: '2024-08-07T21:54:04.000Z' createdDate: type: string description: The date and time that the service was ordered. format: date-time example: '2024-08-07T21:54:01.000Z' completedDate: type: string format: date-time example: '2024-08-07T21:54:03.000Z' dateCompleted: type: string format: date-time example: '2024-08-08T14:34:59.271Z' timeToComplete: type: string example: 16 hours source: type: string rawDataType: type: string rawDataKey: type: string reportHtmlSecureDocumentId: type: string serviceId: type: string enum: - fa226cb7-1214-4cdf-9296-6120a7376926 additionalInfo: type: string records: type: array description: Records found from the criminal search. items: type: object properties: comments: type: string caseNumber: type: string example: 123456CF012155YXYXMB jurisdiction: type: string example: NJ-ESSEX fileDate: type: string format: date example: '2019-07-10' charge: type: string example: 1. Possession Of Schedule 4 Substance offenseType: type: string example: Felony disposition: type: string example: Pre Trial Intervention dispositionDate: type: string format: date example: '2019-08-01' nameOnRecord: type: string example: JONES, STEPHEN state: type: string example: NJ county: type: string example: ESSEX contextualData: type: string DetailsLegal: title: DetailsLegal type: object description: Details from a legal service. examples: - dateCompleted: 1713571200000 timeToComplete: instant additionalInfo: null type: pdf uri: Disclosure-abc1de23-45c0-4443-928b-8729790c6e07 ackData: sendReport: true valid: true list: - legalType: general-ca-disclosure signature: Jack Williams - legalType: state-city-all-disclosure signature: Jack Williams properties: dateCompleted: type: number example: 1713571200000 timeToComplete: type: string example: instant additionalInfo: type: - string - 'null' type: type: string example: pdf uri: type: string ackData: allOf: - type: object properties: valid: type: boolean - oneOf: - $ref: '#/components/schemas/LegalAcknowledgmentSignature' - $ref: '#/components/schemas/LegalAcknowledgmentDisclosures' - $ref: '#/components/schemas/LegalAcknowledgmentDisclosure' AnalyteDetails: title: AnalyteDetails type: object properties: resultId: type: string description: The ID of the analyte result. result: type: string enum: - Positive - Negative - Withheld - Retest Recommended description: The analyte result. panelId: type: string description: The service provider's ID for the drug panel. analyteId: $ref: '#/components/schemas/AnalyteID' analyte: $ref: '#/components/schemas/AnalyteName' specimenType: type: string enum: - Urine - Breath screeningCutoffValue: type: string description: The numeric value of the cutoff concentration for the screening test. example: '10' screeningCutoffUnit: type: string description: The unit of measurement associated with the screening cutoff value. example: ng/mL confirmationCutoffValue: type: string description: The numeric value of the cutoff concentration for the confirmation test. example: '10' confirmationCutoffUnit: type: string description: The unit of measurement associated with the confirmation cutoff value. example: ng/mL quantity: type: string description: The numeric value of the detected concentration. example: '0' examples: - resultId: analyte-negative result: Negative panelId: '1200' analyteId: amphetamines-amp analyte: Amphetamines (AMP) specimenType: Urine screeningCutoffValue: '1000' screeningCutoffUnit: ng/mL confirmationCutoffValue: '500' confirmationCutoffUnit: ng/mL quantity: '0' AnalyteName: title: AnalyteName type: string enum: - 6-Monoacetylmorphine - Amphetamine - Amphetamines - Amphetamines (AMP) - Amphetamines (MET) - Anabolic Steroids - Antidepressants - Barbiturates - Benzodiazepines - Buprenorphine - Butorphanol - Carisoprodol - Chromate - Cocaine - Cotinine - Ethanol Breath - Ethanol Urine - Fentanyl - Hydrocodone - Hydrocodone/Hydromorphone - Ketamine - Marijuana - MDMA/MDA - Meperidine - Meprobamates - Methadone - Methamphetamine - Methamphetamines - Methaqualone - Nalbuphine - Naltrexone - Nicotine - Opiates - Oxycodone - Oxycodone/Oxymorphone - Oxymorphone - PCP - Pentazocine - Propoxyphene - Specific Gravity - Stimulants - Synthetic Cannabinoids - Synthetic Opiates - Tramadol - Tricyclics - Zolpidem (Ambien) description: The name of the analyte. ServiceTypeId: title: ServiceTypeId type: string description: 'The unique ID of the service type. A service can be one of the following types: screening, legal, payment, identity, or shipment.' enum: - 30bc2c03-c8dd-409a-8da6-e0070ea6a681 - a3b74b1b-b665-40be-bad2-2a49c801cf3f - service-type-payment - service-type-idv - service-type-shipment DetailsNationalCriminal: title: DetailsNationalCriminal type: object description: Details from a national criminal search. examples: - serviceId: d8e3dbdb-c2d7-4787-9736-86fffab74da4 dateCompleted: '2024-08-14T14:33:36.197+00:00' timeToComplete: 2 days records: - state: FL county: Putnam County charge: GRAND THEFT AUTO offenseType: FELONY disposition: ADJUDICATED GUILTY/DELINQUENT dispositionDate: '2018-05-15' caseNumber: 11103000089CFYX contextualData: state=FL county=Putnam County charge=GRAND THEFT AUTO - state: FL county: Putnam County charge: CRIMINAL MISCHIEF - MORE THAN $200 LESS THAN $1000 offenseType: MISDEMEANOR disposition: DROPPED/ABANDONED BY PROSECUTOR dispositionDate: '2018-05-15' caseNumber: 11106000525CFMX contextualData: state=FL county=Putnam County charge=CRIMINAL MISCHIEF - MORE THAN $200 LESS THAN $1000 properties: serviceId: type: string enum: - d8e3dbdb-c2d7-4787-9736-86fffab74da4 dateCompleted: type: string format: date-time example: '2024-05-17T19:47:14.885+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string records: type: array description: Records found from the criminal search. items: type: object properties: state: type: string example: FL county: type: string example: Putnam County charge: type: string example: GRAND THEFT AUTO offenseType: type: string example: FELONY disposition: type: string example: DROPPED/ABANDONED BY PROSECUTOR dispositionDate: type: string format: date example: '2018-05-15' caseNumber: type: string example: 11103000089CFYX comments: type: string contextualData: type: string CaseOrderDataOHSServiceSubstitutions: title: CaseOrderDataOHSServiceSubstitutions type: object description: 'The order data when `caseOrderDataTypeId` is `codt-ohs-service-substitutions`. The `substitutionMap` is an object where each key is a service ID, and the corresponding value is an array of service IDs that are acceptable alternatives for substitution. This mechanism is primarily intended for TB blood tests and drug panel services that are either identical or functionally equivalent. The goal is to expand clinic availability by allowing flexibility in the services that can be used to fulfill an order.' examples: - substitutionMap: service-ohs-tb-quantiferon-gold: - service-ohs-tb-quantiferon-gold - service-ohs-tb-tspot-test service-drug-5-panel: - service-drug-5-panel - service-drug-300C-crl - service-drug-35105N-panel properties: substitutionMap: type: object description: The substitutionMap defines service ids that we can consider substituting. This is an object where each key is a service ID, and the corresponding value is an array of service IDs that are acceptable alternatives for substitution. additionalProperties: type: array items: type: string ConfigValuesDrugPolicy: title: ConfigValuesDrugPolicy type: string enum: - company-default - reorder - reorder-and-contact - reorder-once-contact - do-not-reorder description: The configuration options for a drug policy. default: company-default DetailsFACIS: title: DetailsFACIS type: object examples: - dateCompleted: '2024-06-17T22:03:58.586+00:00' timeToComplete: 2 days additionalInfo: '' records: - sanctionType: Board Action sanctionDate: '2020-01-28' contextualData: sanctionType=Board Action description: Details from a Fraud Abuse Control Information System (FACIS) search. properties: dateCompleted: type: string format: date-time example: '2024-06-17T22:03:58.586+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string records: type: array items: type: object properties: sanctionType: type: string sanctionDate: type: string format: date example: '2015-04-18' specialty: type: string occupation: type: string comments: type: string upin: type: string contextualData: type: string ConfigValuesEducationVerification: title: ConfigValuesEducationVerification type: string enum: - docs-acceptable - psv - psv-first description: The configuration options for education verification. default: docs-acceptable ServiceSubCategoryId: title: ServiceSubCategoryId type: string description: The unique ID of the service subcategory. enum: - service-subcat-drug - service-subcat-tb - service-subcat-titer - service-subcat-vacc - service-subcat-physical ConfigAliasName: title: AliasNameConfiguration type: object description: The configuration that determines how to run aliases for criminal screenings. required: - rawValue - appliesTo - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesAlias' description: The configuration setting that specifies if and how aliases are applied to screenings. appliesTo: type: object description: The services that the configuration applies to. required: - serviceIds - serviceCategoryIds - serviceSubCategoryIds properties: serviceIds: type: array description: A list of applicable services by ID. items: type: string default: [] serviceCategoryIds: type: array description: A list of applicable service categories by ID. items: type: string default: service-cat-criminal serviceSubCategoryIds: type: array description: A list of applicable service subcategories by ID. items: type: string default: [] pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: No aliases. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies the method used to select aliases. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: No Aliases configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Alias Name Configuration ConfigValuesAlias: title: ConfigValuesAlias type: string enum: - no-alias - alias-all - alias-all+hits-only - alias-mnv - alias-mnv+hits-only description: The options for an alias configuration. default: no-alias JurisdictionCounties: title: JurisdictionCounties type: object description: Jurisdiction lookup entity. required: - state properties: city: type: string description: The city for which relevant jurisdictions will be returned. Required if `county` is not passed. county: type: string description: The county for which relevant jurisdictions will be returned. **Known issue:** The API currently requires this property to be passed. state: type: string description: 'The state for which relevant jurisdictions will be returned. ' CaseDataStatusID: title: CaseDataStatusID description: 'The status ID of a case data record (an instance of a service). See [Case data statuses](docs/reference/case-data-status.md) for more details. - acknowledge (done positive): 1a8490cb-084d-4209-bf2f-d46e41d760d6 - clear (done and good): e086eea7-e4b7-4c74-ac04-4c3b51c23a33 - consider (done and needs review): f657c777-c38d-489b-ac26-dd9bf0a88724 - not_found (unable to verify): 96e0420a-4396-4bd1-9b54-447f00eb3ed8 - canceled (not performed): 3d726502-d2e2-4d10-859b-8a218f22086d - complete (done without prejudice): case-data-status-complete - pending (in progress): 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 - error (error during processing): case-data-status-error' type: string enum: - 1a8490cb-084d-4209-bf2f-d46e41d760d6 - e086eea7-e4b7-4c74-ac04-4c3b51c23a33 - f657c777-c38d-489b-ac26-dd9bf0a88724 - 96e0420a-4396-4bd1-9b54-447f00eb3ed8 - 3d726502-d2e2-4d10-859b-8a218f22086d - case-data-status-complete - 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 - case-data-status-error CaseSecondaryStatus: title: CaseSecondaryStatus type: string enum: - Waiting for Authorization - Authorization in Progress - Waiting for Parental Consent - Verifying Candidate Input - Reviewing Order - Consider - Canceled ConfigDiluteDrug: title: DiluteDrugPolicy type: object description: The configuration that determines how to handle dilute samples in drug screenings. required: - rawValue - appliesTo - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesDrugPolicy' description: The configuration setting that specifies if and how screenings should be reordered. appliesTo: type: object description: The services that the configuration applies to. required: - serviceIds - serviceCategoryIds - serviceSubCategoryIds properties: serviceIds: type: array description: A list of applicable services by ID. items: type: string default: [] serviceCategoryIds: type: array description: A list of applicable service categories by ID. items: type: string default: [] serviceSubCategoryIds: type: array description: A list of applicable service subcategories by ID. items: type: string default: service-subcat-drug pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Refer to company settings. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies next steps when a Drug sample is dilute. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Refer To Company Settings configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Dilute Drug Policy ServiceTypeName: title: ServiceTypeName type: string description: The type of service. enum: - Screening - Legal - Payment - Identity - Shipment CaseOrderDataJurisdiction: title: CaseOrderDataJurisdiction type: object description: The candidate data when `caseOrderDataTypeId` is `codt-address`. required: - city - state - county properties: city: type: string example: Manchester state: type: string description: The two-letter state code. example: NH county: type: string example: Hillsborough autoProcessJurisdictions: type: boolean default: false description: If true, jurisdiction order data will be automatically created based on the services ordered. If false, jurisdiction order data will be specified for the jurisdiction-based search type being ordered. CaseOrderDataOHSAddress: title: CaseOrderDataOHSAddress type: object description: The order data (address for finding nearby clinics) when `caseOrderDataTypeId` is `codt-ohs-scheduling-address`. required: - address1 - city - state - postalCode - country properties: address1: type: string address2: type: string city: type: string state: type: string description: The two-letter state code. postalCode: type: string country: type: string description: The two-letter country code. examples: - address1: 6 Flagstone Drive address2: Apartment 2 city: Hudson state: NH postalCode: '03051' country: US CaseOrderDataJurisdictionFederal: title: CaseOrderDataJurisdictionFederal type: object description: The candidate data when `caseOrderDataTypeId` is `codt-fed-district`. required: - district properties: district: type: string example: New Hampshire District Court LegalAcknowledgmentDisclosure: title: LegalAcknowledgmentDisclosure type: object properties: sendReport: type: boolean description: If true, a report notification will be emailed to the candidate when the report is finished. default: false signature: type: string description: The name entered into the signature input field on the legal step during candidate onboarding. This value might not be exactly the same as the name that the case was ordered under. CaseOrderDataCPLC: title: CaseOrderDataCPLC type: object description: The candidate data when `caseOrderDataTypeId` is `codt-cplc`. examples: - cplcId: cb3dac22-db86-44df-8193-877559b3e8dc fields: - fieldId: licenseNumber value: LN123456 - fieldId: firstName value: Lucian - fieldId: lastName value: Williams - fieldId: state value: NY required: - cplcId - fields properties: cplcId: type: string description: The unique ID of the professional license or certification. See [Professional license and certification](docs/reference/cplc.md) for a list of possible values. fields: type: array description: Details about the candidate's professional license or certification. Call [GET `/service/cplc/id/{cplcId}`](karma-api-openapi.yaml/paths/~1service~1cplc~1id~1{cplcId}/get) for a list of required fields for the specific professional license or certification. items: type: object required: - fieldId - value properties: fieldId: type: string enum: - licenseNumber - firstName - lastName - middleInitial - certifyingBody - state - additionalInfo - certifyingBodyMemberId - certifyingBodyVerificationPin - expirationDate - issueDate - licenseTitle description: The identifier for a specific detail of the professional license or certification. value: type: string description: The candidate's information corresponding to a specific field. secureDocumentIds: type: array description: The IDs of uploaded secure documents that will be associated to the CPLC record. This optional field can be applied when providing data on behalf of the candidate. items: type: string DetailsOtherService: title: DetailsOtherService type: object description: Details from a state-specific search, Content-Based SSN Verification (CBSV), Death Master File (DMF), county civil court, socia media, or bankruptcy check. examples: - status: Clear statusId: e086eea7-e4b7-4c74-ac04-4c3b51c23a33 pendingStatusId: '' additionalInfo: '' dateCompleted: '2024-06-18T23:14:06.594Z' timeToComplete: 5 days source: karmacheck properties: status: type: string statusId: type: string pendingStatusId: type: string additionalInfo: type: string dateCompleted: type: string format: date-time example: '2024-06-17T22:03:58.586Z' timeToComplete: type: string example: 2 days source: type: string example: karmacheck DetailsPayment: title: DetailsPayment type: object examples: - dateCompleted: 1718670225405 timeToComplete: instant additionalInfo: null orderPrice: 2995 paymentStatus: paid records: - action: payment paymentDate: 2024-06-18 00:23:43 UTC amount: 2995 paymentProviderId: payment-provider-stripe description: Details of a payment. properties: dateCompleted: type: number example: 1718670225405 timeToComplete: type: string example: instant additionalInfo: type: - string - 'null' orderPrice: type: integer example: 2995 description: The order amount in cents. For example, `2995` is $29.95. paymentStatus: type: string enum: - unpaid - paid - payment_failure - refunded - partial_refund records: type: array items: type: object properties: action: type: string enum: - payment - payment_failure - refund paymentDate: type: string example: 2024-06-18 00:23:43 UTC amount: type: number example: 2995 paymentProviderId: type: string example: payment-provider-stripe OrderConfig: title: OrderConfig type: object description: 'Options that describe how to run certain screenings for a case. See [Order configuration](docs/reference/order-configuration.md) for details on all configuration options. All properties are optional, but a configuration will be set for all applicable screenings on the package regardless of whether those screenings are ordered. Therefore, aside from the `contacts` object, the default configuration will be used if one is not set.' properties: contacts: type: array description: A list of people to contact about the case. items: $ref: '#/components/schemas/Contact' aliasNameConfiguration: $ref: '#/components/schemas/ConfigValuesAlias' ohsDrugPassportExpirationPolicy: $ref: '#/components/schemas/ConfigValuesOhsDrugPassportExpirationPolicy' lostOrIncompleteOHSDrugPolicy: $ref: '#/components/schemas/ConfigValuesDrugPolicy' diluteDrugPolicy: $ref: '#/components/schemas/ConfigValuesDrugPolicy' serviceConfigs: type: object description: Services with configuration options. properties: 9ac65633-b4c4-4062-875c-3556db9d2a08: type: object description: The configuration for employment verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The method for verifying employment. service-employment-income: type: object description: The configuration for employment income verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The method for verifying employment and income. 85307784-1f84-471a-8596-c8ea088c3a62: type: object description: The configuration for education verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEducationVerification' description: The method for verifying education. service-ohs-tb-quantiferon-gold: type: object description: The configuration for Quantiferon testing. properties: substitutionPolicy: $ref: '#/components/schemas/ConfigValuesQuantiferon' description: The policy for Quantiferon testing substitution. service-ohs-tb-tspot-test: type: object description: The configuration for T-Spot testing. properties: substitutionPolicy: $ref: '#/components/schemas/ConfigValuesTspot' description: The policy for T-Spot testing substitution. DetailsGlobalWatchlist: title: DetailsGlobalWatchlist type: object examples: - dateCompleted: '2024-04-05T20:22:07.735+00:00' timeToComplete: instant records: - provider: Federal Bureau of Prisons charge: UNSPECIFIED offenseType: Crime referenceNumber: 010203-0203 contextualData: provider=Federal Bureau of Prisons jurisdiction= charge=UNSPECIFIED offenseType=Crime - provider: System for Award Management (SAM) - Excluded Parties List charge: UNSPECIFIED offenseType: Crime contextualData: provider=System for Award Management (SAM) - Excluded Parties List jurisdiction= charge=UNSPECIFIED offenseType=Crime description: Details from a global watchlist records check. properties: dateCompleted: type: string format: date-time example: '2024-06-17T20:24:48.920Z' timeToComplete: type: string example: instant additionalInfo: type: string records: type: array items: type: object properties: provider: type: string jurisdiction: type: string charge: type: string offenseType: type: string dispositionDate: type: string format: date example: '2015-04-15' disposition: type: string referenceNumber: type: string comments: type: string contextualData: type: string DetailsSSN: title: DetailsSSN type: object examples: - dateCompleted: '2024-06-17T18:58:20.113+00:00' timeToComplete: instant records: - firstName: Jack lastName: Williams dob: '1983-03-15' city: New York state: NY zip: '10031' ssn: XXX-XX-XXXX dateFirstReported: 2019-02 dateLastReported: 2019-07 nameScore: 30 dobMatch: false county: NEW YORK - firstName: Jack lastName: Williams dob: '1983-03-15' city: Montclair state: NJ zip: '07042' ssn: XXX-XX-XXXX dateFirstReported: 2018-01 dateLastReported: 2018-05 nameScore: 30 dobMatch: false county: ESSEX results: true description: Details from a Social Security number (SSN) trace. properties: dateCompleted: type: string format: date-time example: '2024-06-17T18:58:20.113+00:00' timeToComplete: type: string example: instant additionalInfo: type: string records: type: array items: type: object properties: firstName: type: string lastName: type: string middleName: type: string dob: type: string format: date example: '1983-03-15' city: type: string state: type: string zip: type: string ssn: type: string enum: - XXX-XX-XXXX dateFirstReported: type: string example: 2018-01 dateLastReported: type: string example: 2018-05 nameScore: type: integer dobMatch: type: boolean county: type: string results: type: boolean description: True if records were found; false otherwise. This does not indicate good or bad results. CaseData: title: CaseData type: object required: - id - description - caseId - serviceId - serviceName - serviceTypeId - serviceTypeName - statusId - status - statusDisplayName - crStamp - modStamp - groupProfileId - candidateId - storageId - details properties: id: type: string description: The unique identifier of the case data; elsewhere referred to as a `caseDataId`. format: uuid description: type: string description: The description associated with the `serviceId` of this case data record. A possible value is the name of the service. caseId: type: string format: uuid serviceId: type: string description: The unique identifier of the service that the case data represents. See [Service](docs/reference/service.md) for a list of possible values. serviceName: description: The name of the service. See [Service](docs/reference/service.md) for a list of supported services. type: string serviceTypeId: $ref: '#/components/schemas/ServiceTypeId' serviceTypeName: $ref: '#/components/schemas/ServiceTypeName' statusId: $ref: '#/components/schemas/CaseDataStatusID' status: $ref: '#/components/schemas/CaseDataStatus' statusDisplayName: type: string crStamp: type: string format: date-time example: '2024-05-17T00:06:45.000+00:00' modStamp: type: string format: date-time example: '2024-06-18T00:07:39.000+00:00' groupProfileId: type: string format: uuid candidateId: type: string format: uuid storageId: type: string description: The unique identifier of the database record containing the `details` property. format: uuid details: type: string description: The string representation of `detailsObject`. detailsObject: oneOf: - $ref: '#/components/schemas/DetailsNationalCriminal' - $ref: '#/components/schemas/DetailsFederalCriminal' - $ref: '#/components/schemas/DetailsCountyCriminal' - $ref: '#/components/schemas/DetailsStateCriminalCourt' - $ref: '#/components/schemas/DetailsStateCriminalDatabase' - $ref: '#/components/schemas/DetailsDrug' - $ref: '#/components/schemas/DetailsOHS' - $ref: '#/components/schemas/DetailsEducation' - $ref: '#/components/schemas/DetailsEmployment' - $ref: '#/components/schemas/DetailsMotorVehicle' - $ref: '#/components/schemas/DetailsSSN' - $ref: '#/components/schemas/DetailsSexOffender' - $ref: '#/components/schemas/DetailsGlobalWatchlist' - $ref: '#/components/schemas/DetailsFACIS' - $ref: '#/components/schemas/DetailsIdentity' - $ref: '#/components/schemas/DetailsCPLC' - $ref: '#/components/schemas/DetailsOIG' - $ref: '#/components/schemas/DetailsOtherService' - $ref: '#/components/schemas/DetailsInternational' - $ref: '#/components/schemas/DetailsLegal' - $ref: '#/components/schemas/DetailsPayment' - $ref: '#/components/schemas/DetailsMaskShipment' description: Details of the case data. The properties vary based on the type of service. serviceCategory: $ref: '#/components/schemas/ServiceCategory' serviceCategoryId: $ref: '#/components/schemas/ServiceCategoryId' serviceSubCategory: $ref: '#/components/schemas/ServiceSubCategory' type: string serviceSubCategoryId: $ref: '#/components/schemas/ServiceSubCategoryId' type: string pendingStatus: $ref: '#/components/schemas/CaseDataPendingStatus' type: string pendingStatusId: $ref: '#/components/schemas/CaseDataPendingStatusID' type: string locked: type: boolean CaseDataPendingStatus: title: CaseDataPendingStatus type: string enum: - Drug Test Appointment Scheduled - Drug Test Appointment Change - Drug Test Appointment Canceled - Drug Test Appointment Requested - Drug Test Sent to Lab - Drug Test Received at Lab - Drug Test In Review - Drug Test Pending - Drug Test Expired - Appointment Scheduled - Appointment Rescheduled - Appointment Canceled - Appointment Requested - Pending - Appointment No Show - Partial Results - Refusal to Test - Suspended - Medical Review - Not Performed ServiceGroupServicesCase: title: ServiceGroupServicesCase examples: - serviceGroupServices: - serviceGroupId: 8afb91ff-7958-4f42-90e1-9bfed7db9bbf serviceGroupName: Basic Check 2023-04-13T20:51:49.938Z serviceGroupPrice: 1337 serviceGroupDescription: Common services for a basic background check serviceId: 03635d39-c9df-418f-948d-10d38a7e06db serviceName: National Sex Offender Search Alt serviceDescription: Search for candidate sex offender history serviceTypeId: 30bc2c03-c8dd-409a-8da6-e0070ea6a681 serviceTypeName: Screening serviceGroupEnabled: true serviceEnabled: true serviceAutoProcessEnabled: true serviceTypeEnabled: true serviceCategory: Criminal Check serviceCategoryId: service-cat-criminal conditional: false defaultSelected: false enabled: true serviceGroupServicesId: d2ff35ec-4da4-4a82-bb72-80980fc658ff caseId: 1234a56b-24ed-9874-ae77-9fccc6a25474 packageName: Basic Check candidateId: 1b23c456-d211-42c8-dde8-8a5f84c9def2 groupProfileId: ab0123c4-de56-4c96-cc22-06ae7e123fd2 allOf: - $ref: '#/components/schemas/ServiceGroupServicesAll' - type: object required: - serviceGroupServices properties: serviceGroupServices: type: array description: A list of services, each containing detailed information about a service. items: type: object required: - caseId - packageName - candidateId - groupProfileId properties: caseId: type: string packageName: type: string description: The name of the package that was ordered for the case. candidateId: type: string description: The ID of the candidate that's associated with the case. groupProfileId: type: string description: The ID of the group that the case was ordered under. ServiceCategory: title: ServiceCategory type: string description: The category that a service belongs to. enum: - Payment - Identity Verification - Criminal Check - Motor Vehicle Record Check - Verification - Occupational Health Screening - Professional License CaseOrderDataEducation: title: CaseOrderDataEducation type: object description: 'The candidate data when `caseOrderDataTypeId` is `codt-education`. **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. 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 educationTypeDescription: type: string description: A description of the education type. This should be used when `educationType` is other. degree: type: string description: The educational degree. Recommended when `educationType` is college/university or technical/trade school. major: type: string description: The candidate's field of study. Recommended when `educationType` is college/university or technical/trade school. 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 two-letter country code. Recommended to be included in *all* requests. 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. current: type: boolean description: If true, the candidate is currently enrolled at the institution. If false, the candidate is not currently enrolled. Recommended to be included in *all* requests. (Required true if `monthEnd` and `yearEnd` are not provided) default: false monthEnd: type: string description: The month in which the candidate completed their education. (Required if `current` is false or not provided) yearEnd: type: string description: The year in which the candidate completed their education. (Required if `current` is false or not provided) nameIfDifferentFlag: type: boolean description: If true, the candidate attended or is attending the institution under a different name. If false, the candidate's name on record with the institution is the same as the candidate's name recorded for the case. nameIfDifferent: type: string description: The candidate's name that's on record with the institution. contact: type: object description: The institution's contact information. **Known issue:** The API currently requires this object to be passed (either empty or with any of its optional properties). properties: website: type: string email: type: string phone: type: string secureDocumentIds: type: array description: The IDs of uploaded secure documents that will be associated to the education record. This optional field can be applied when providing data on behalf of the candidate. items: type: string CaseOrderDataAlias: title: CaseOrderDataAlias type: object description: The candidate data when `caseOrderDataTypeId` is `codt-alias`. required: - givenName - familyName properties: givenName: type: string description: Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. middleName: type: string description: Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. familyName: type: string description: Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. DetailsStateCriminalCourt: title: DetailsStateCriminalCourt type: object description: Details from a state criminal court search. examples: - serviceId: c407f6dd-523e-4627-a4d9-8f52d30ee744 dateCompleted: '2024-05-17T19:47:14.885+00:00' timeToComplete: 2 days jurisdictions: - status: f657c777-c38d-489b-ac26-dd9bf0a88724 jurisdiction: FLORIDA records: - state: FLORIDA charge: 1. Unregistered Motor Vehicle offenseType: Traffic disposition: Nolle Prosse dispositionDate: '2012-10-16' caseNumber: 123456CT024900YXYXXSB jurisdiction: FLORIDA fileDate: '2008-08-17' contextualData: state=FLORIDA jurisdiction=FLORIDA externalSearchAndHasResults: false properties: serviceId: type: string enum: - c407f6dd-523e-4627-a4d9-8f52d30ee744 dateCompleted: type: string format: date-time example: '2024-05-17T19:47:14.885+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string jurisdictions: type: array description: Details about each jurisdictional search. items: type: object properties: status: $ref: '#/components/schemas/CaseDataStatusID' description: "The status ID of the jurisdictional search.\n\n- acknowledge (done positive): 1a8490cb-084d-4209-bf2f-d46e41d760d6\n- clear (done and good): e086eea7-e4b7-4c74-ac04-4c3b51c23a33\n- consider (done and needs review): f657c777-c38d-489b-ac26-dd9bf0a88724 \n- not_found (unable to verify): 96e0420a-4396-4bd1-9b54-447f00eb3ed8\n- canceled (not performed): 3d726502-d2e2-4d10-859b-8a218f22086d\n- complete (done without prejudice): case-data-status-complete\n- pending (in progress): 8f29e0de-10f2-4c84-8379-16c6eb7cdf64\n- error (error during processing): case-data-status-error" jurisdiction: type: string example: FLORIDA records: type: array description: Records found from the criminal search. items: type: object properties: state: type: string example: FLORIDA charge: type: string example: 1. Unregistered Motor Vehicle offenseType: type: string example: Traffic disposition: type: string example: Nolle Prosse dispositionDate: type: string format: date example: '2012-10-16' caseNumber: type: string example: 123456CT024900YXYXXSB comments: type: string jurisdiction: type: string example: FLORIDA fileDate: type: string format: date example: '2008-08-17' contextualData: type: string externalSearchAndHasResults: type: boolean CaseOrderDataDrugReasonForTest: title: CaseOrderDataDrugReasonForTest type: object description: The reason for the drug test. examples: - reasonForTest: pre-employment properties: reasonForTest: type: string enum: - pre-employment - followup - post-accident - return-to-duty description: The reason for the drug test. Defaults to `pre-employment` if not provided. default: pre-employment ConfigValuesOhsDrugPassportExpirationPolicy: title: ConfigValuesOhsDrugPassportExpirationPolicy type: string enum: - company-default - reissue - reissue-and-contact - reissue-once-contact - contact-customer - do-not-reissue description: The configuration options for an ePassport expiration policy. default: company-default ConfigQuantiferon: title: Quantiferon type: object description: The configuration for Quantiferon testing. required: - substitutionPolicy properties: substitutionPolicy: type: object description: The substitution policy that's configured for the test. required: - rawValue - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesQuantiferon' description: The configuration setting that specifies whether the test can be replaced. pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Refer to company settings. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies if T-Spot can be ordered in place of Quantiferon Gold when Quantiferon Gold is unavailable. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Refer To Company Settings configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Substitution Policy InvitationStatusID: title: InvitationStatusID type: string enum: - 3f5e6898-6641-4685-8ee0-1363b7e10c98 - b5af27f7-8a03-4820-b2bd-82587dcacf5b - d1962405-dd97-48f2-bede-530c2895481f - 0f6acacc-71c4-43ec-80fa-941ff71c0c16 description: 'The status ID of a case invitation. See [Invitation status](docs/reference/invitation-status.md) for more details about each possible status. - pending: 3f5e6898-6641-4685-8ee0-1363b7e10c98 - expired: b5af27f7-8a03-4820-b2bd-82587dcacf5b - completed: d1962405-dd97-48f2-bede-530c2895481f - cancelled: 0f6acacc-71c4-43ec-80fa-941ff71c0c16 ' CaseResult: title: CaseResult type: string enum: - Open - Placed - Pre-Adverse Action - Dispute Adverse Action - Adverse Action DetailsDrug: title: DetailsDrug type: object description: Details from a drug screening. examples: - dateCompleted: '2024-06-18T16:54:10.635Z' timeToComplete: 3 days effectiveDate: '2024-06-18T16:54:00.000Z' externalId: kj0cKdOSgqKlaCRm2LSQ scheduledDate: '2024-06-13T16:53:00.000Z' expirationDate: '2024-06-20T16:53:00.000Z' clientName: Example Company clientAccount: '629236' clientSubAccount: '26' clinicId: '9588' clinicName: Test Clinic clinicAddress1: 7500 W 110th Street clinicAddress2: '' clinicCity: Omaha clinicState: NE clinicZip: '66210' clinicPhoneNumber: 800-555-0175 clinicFaxNumber: '8005550100' network: In Network Tier 1 firstName: Jack lastName: Williams status: Negative chainOfCustody: '2123312312' collectionDate: '2024-06-13T19:54:00.000Z' collectionData: regulation: Non-DOT specimenType: Breath dilute: Not Dilute analytes: resultId: analyte-negative result: Negative panelId: 'null' analyteId: ethanol-breath analyte: Ethanol Breath specimenType: Breath screeningCutoffValue: '10' screeningCutoffUnit: ng/mL confirmationCutoffValue: '10' confirmationCutoffUnit: ng/mL quantity: '0' confirmationNumber: AI123456789 labReceivedDate: '2024-06-13T20:54:00.000Z' labReportDate: '2024-06-14T16:54:00.000Z' verificationDate: '2024-06-15T16:54:00.000Z' labName: Example Lab collectionSite: '12' collectionSiteInNetwork: In Network Tier 1 collectionSitePhoneNumber: 800-555-0175 eCupCollection: Not an eCup Collection donorName: Williams, Jack dob: 3/15/1983 ssnLast4: '3333' homePhone: '' homePhoneExt: '' workPhone: 800-555-0180 workPhoneExt: '' otherIDType: '' reasonForTest: Pre-Employment specimenCollector: JD locationInfo: Test Clinic mroAddress: 8140 Ward Parkway mroCity: Omaha mroName: Dr. Kirk Roberts, M.D. mroPhone: 800-555-0190 mroState: NE mroZip: '64114' result: negative resultCode: '1' resultId: drugtest-negative comments: Results are clean additionalInfo: '' properties: dateCompleted: type: string format: date-time example: '2024-06-18T16:54:10.635Z' timeToComplete: type: string example: 3 days effectiveDate: type: string format: date-time example: '2024-06-18T16:54:00.000Z' externalId: type: string description: The service provider's ID for the candidate. scheduledDate: type: string format: date-time example: '2024-06-13T16:53:00.000Z' expirationDate: type: string format: date-time example: '2024-06-20T16:53:00.000Z' description: The expiration date for the drug test. clientName: type: string description: The name of the company ordering the screening. clientAccount: type: string description: The ordering company's account. clientSubAccount: type: string description: The ordering company's subaccount. clinicId: type: string description: The ID of the clinic. clinicName: type: string description: The name of the clinic that's performing the screening. clinicAddress1: type: string description: The clinic's address. clinicAddress2: type: string description: The clinic's address, continued. clinicCity: type: string description: The clinic's city. clinicState: type: string description: The clinic's state clinicZip: type: string description: The clinic's zip code. clinicPhoneNumber: type: string description: The clinic's phone number. clinicFaxNumber: type: string description: The clinic's fax number. network: type: string description: The network coverage for the clinic. example: In Network Tier 1 firstName: type: string description: The candidate's first name. lastName: type: string description: The candidate's last name. status: type: string description: The readable text for the status. chainOfCustody: type: string collectionDate: type: string format: date-time example: '2024-06-13T19:54:00.000Z' description: The date the specimen was collected. collectionData: type: object properties: regulation: type: string enum: - DOT - Non DOT specimenType: type: string enum: - Urine - Breath dilute: type: string enum: - Dilute - Not Dilute analytes: $ref: '#/components/schemas/AnalyteDetails' confirmationNumber: type: string description: The service provider confirmation number. labReceivedDate: type: string format: date-time example: '2024-06-13T20:54:00.000Z' description: The date the specimen was received at the lab. labReportDate: type: string format: date-time example: '2024-06-14T16:54:00.000Z' description: The date the specimen results were reported by the lab. verificationDate: type: string format: date-time example: '2024-06-15T16:54:00.000Z' description: The date the specimen was verified by the lab or medical review officer (MRO). labName: type: string description: The name of the lab that's analyzing the specimen. collectionSite: type: string description: The collection site location. collectionSiteInNetwork: type: string description: The network coverage for the clinic. example: In Network Tier 1 collectionSitePhoneNumber: type: string description: The collection site's phone number. eCupCollection: type: string enum: - Not an eCup Collection - eCup Collection donorName: type: string description: The candidate's full name, last name followed by first name. dob: type: string description: The candidate's date of birth. example: 1/1/1980 ssnLast4: type: string description: The last four digits of the candidate's Social Security number. homePhone: type: string description: The candidate's home phone number. homePhoneExt: type: string description: The candidate's home phone extension. workPhone: type: string description: The candidate's work phone number. workPhoneExt: type: string description: The candidate's work phone extension. otherID: type: string description: An alternate form of identification. otherIDType: type: string description: The type of alternate identification. example: Passport reasonForTest: type: string description: The reason for the test. example: Pre-employment specimenCollector: type: string description: The name of the specimen collector. locationInfo: type: string description: Information provided by the lab about the location. mroAddress: type: string description: The MRO's address. mroCity: type: string description: The MRO's city. mroName: type: string description: The MRO's name. mroPhone: type: string description: The MRO's phone number. mroState: type: string description: The MRO's state. mroZip: type: string description: The MRO's zip code. result: type: string enum: - positive - negative - withheld - retest recommended description: The readable text for the drug screening result. resultCode: type: string description: The service provider's raw result for the drug screening. resultId: type: string description: The unique ID of the result for the drug screening. comments: type: string description: Comments from the drug screening. additionalInfo: type: string ConfigLostOrIncompleteOHSDrug: title: LostOrIncompleteOHSDrugPolicy type: object description: The configuration that determines how to handle lost or incomplete samples for OHS and drug screenings. required: - rawValue - appliesTo - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesDrugPolicy' description: The configuration setting that specifies if and how screenings should be reordered. appliesTo: type: object description: The services that the configuration applies to. required: - serviceIds - serviceCategoryIds - serviceSubCategoryIds properties: serviceIds: type: array description: A list of applicable services by ID. items: type: string default: [] serviceCategoryIds: type: array description: A list of applicable service categories by ID. items: type: string default: service-cat-ohs serviceSubCategoryIds: type: array description: A list of applicable service subcategories by ID. items: type: string default: [] pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Refer to company settings. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies next steps when an OHS/Drug sample is lost or incomplete. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Refer To Company Settings configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Lost or Incomplete OHS/Drug Policy DetailsEducation: title: DetailsEducation type: object examples: - dateCompleted: '2024-05-17T21:14:30.846+00:00' timeToComplete: 4 days records: - statusId: 1a8490cb-084d-4209-bf2f-d46e41d760d6 institution: Boston University location: Boston, MA receivedResults: 'yes' applicantProvided: degree: BA major: Communications dateSpan: 1995-08 TO 1999-05 institutionProvided: degree: BA major: Communications dateSpan: 1995-08 TO 1999-05 testimonyId: f3dd7129-e553-4870-b99e-472de8d6c522 - statusId: 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 description: Details from an education verification. properties: dateCompleted: type: string format: date-time example: '2024-05-17T21:14:30.846+00:00' timeToComplete: type: string example: 4 days additionalInfo: type: string records: type: array items: type: object properties: statusId: $ref: '#/components/schemas/EducationVerificationIndividualRecordStatus' institution: type: string location: type: string receivedResults: $ref: '#/components/schemas/EducationEmploymentReceivedResults' applicantProvided: type: object properties: degree: type: string major: type: string gpa: type: string dateSpan: type: string example: 1995-08 TO 1999-05 comments: type: string institutionProvided: type: object properties: degree: type: string major: type: string gpa: type: string dateSpan: type: string example: 1995-08 TO 1999-05 comments: type: string testimonyId: type: string description: Associated testimony identifier searchId: type: string description: Associated case data search identifier AnalyteID: title: AnalyteID type: string enum: - 6-monoacetylmorphine - amphetamine - amphetamines - amphetamines-amp - amphetamines-met - anabolic-steroids - antidepressants - barbiturates - benzodiazepines - buprenorphine - butorphanol - carisoprodol - chromate - cocaine - cotinine - ethanol-breath - ethanol-urine - fentanyl - hydrocodone - hydrocodone-hydromorphone - ketamine - marijuana - mdma-mda - meperidine - meprobamates - methadone - methamphetamine - methamphetamines - methaqualone - nalbuphine - naltrexone - nicotine - opiates - oxycodone - oxycodone-oxymorphone - oxymorphone - pcp - pentazocine - propoxyphene - specific-gravity - stimulants - synthetic-cannabionids - synthetic-opiates - tramadol - tricyclics - zolpidem-ambien description: The unique ID of an analyte. CaseOrderDataEmployment: title: CaseOrderDataEmployment type: object description: 'The candidate data when `caseOrderDataTypeId` is `codt-employment`. **Note:** Multiple properties are currently optional, but are strongly recommended to be included in requests.' required: - employer - position - city - state - country - monthBegin - yearBegin - current - 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. position: type: string description: The candidate's position with the employer. 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 two-letter country code. Recommended to be included in *all* requests. monthBegin: type: string description: The month in which the candidate began their employment. Recommended to be included in *all* requests. yearBegin: type: string description: The year in which the candidate began their employment. Recommended to be included in *all* requests. 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 monthEnd: type: string description: The month in which the candidate ended their employment. (Required if `current` is false or not provided) yearEnd: type: string description: The year in which the candidate ended their employment. (Required if `current` is false or not provided) contact: type: object description: The employer's contact information. **Known issue:** The API currently requires this object to be passed (either empty or with any of its optional properties). properties: website: type: string email: type: string phone: type: string 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. default: true incomeAmount: type: string description: The amount earned. This is applicable to Employment Income Verification. incomeFrequency: type: string description: The frequency of the amount earned. This is applicable to Employment Income Verification. example: Annually staffingAgency: type: string description: The Staffing Agency that the candidate is working for the employer through. (If applicable) maxLength: 100 secureDocumentIds: type: array description: The IDs of uploaded secure documents that will be associated to the employment record. This optional field can be applied when providing data on behalf of the candidate. items: type: string ConfigEduVerification: title: EducationVerification type: object description: The configuration for education verification. required: - verificationMethod properties: verificationMethod: type: object description: The verification method that's configured for the screening. required: - rawValue - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesEducationVerification' description: The configuration setting that specifies acceptable forms of verification. pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Documents acceptable. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies the verification method used for this service. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Documents Acceptable configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Verification Method ConfigOhsDrugPassportExpiration: title: OhsDrugPassportExpirationPolicy type: object description: The configuration that determines how to handle expired ePassports for OHS and drug screenings. required: - rawValue - appliesTo - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesOhsDrugPassportExpirationPolicy' description: The configuration setting that specifies if and how ePassports should be reissued. appliesTo: type: object description: The services that the configuration applies to. required: - serviceIds - serviceCategoryIds - serviceSubCategoryIds properties: serviceIds: type: array description: A list of applicable services by ID. items: type: string default: [] serviceCategoryIds: type: array description: A list of applicable service categories by ID. items: type: string default: service-cat-ohs serviceSubCategoryIds: type: array description: A list of applicable service subcategories by ID. items: type: string default: [] pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Refer to company settings. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies next steps when an OHS/Drug ePassport expires. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Refer To Company Settings configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: OHS/Drug Passport Expiration Policy DetailsOHS: title: DetailsOHS type: object description: Details from an occupational health screening, such as a physical, vaccination, titer, or TB test. examples: - dateCompleted: '2024-06-18T00:34:00.000Z' timeToComplete: 3 days effectiveDate: '2024-06-12T00:33:00.000Z' externalId: kj0cKdOSgqKlaCRm2LSQ confirmationNumber: kj0cKdOSgqKlaCRm2LSQ scheduledDate: '2024-06-13T00:33:00.000Z' expirationDate: '2024-06-20T00:33:00.000Z' clientName: Example Company clientAccount: '629236' clientSubAccount: '26' clinicId: '9588' clinicName: Test Clinic clinicAddress1: 7500 W 110th Street clinicAddress2: '' clinicCity: Omaha clinicState: NE clinicZip: '66210' clinicPhoneNumber: 800-555-0175 clinicFaxNumber: '8005550100' network: In Network Tier 1 firstName: Jack lastName: Williams birthDate: 03/15/1983 ssnLast4: '3333' source: escreen physicalID: '238170' verificationType: physical componentId: '35' componentDescription: Chest X-Ray 1 View status: Complete result: Within Normal Limits resultId: ohs-result-165-acknowleged resultCode: '165' resultDate: '2024-06-14T00:34:00.000Z' resultDueToReason: '' resultExpirationDate: '' resultStatusDescription: Within Normal Limits partialReasons: [] examDate: 6/14/2024 followUpDate: '' certExpirationDate: '' tbReadDate: '' comments: Results are clean. clientAddress1: 7878 Guy St clientAddress2: '' clientCity: Omaha clientContact: Rosario S. clientState: NE clientZip: '64086' collectionSitePhoneNumber: 800-555-0155 cdlFlag: '0' overallStatusDescription: Complete physicalReasonDescription: New Certification additionalInfo: '' properties: dateCompleted: type: string format: date-time example: '2024-06-18T00:34:00.000Z' description: The date and time when the service was complete. timeToComplete: type: string example: 3 days effectiveDate: type: string format: date-time example: '2024-06-12T00:33:00.000Z' externalId: type: string description: The service provider's ID for the candidate. confirmationNumber: type: string description: The service provider confirmation number. For eScreen services, this is the ePassport ID. scheduledDate: type: string format: date-time example: '2024-06-13T00:33:00.000Z' expirationDate: type: string format: date-time example: '2024-06-20T00:33:00.000Z' description: The expiration date for the exam. clientName: type: string description: The name of the company ordering the service. clientAccount: type: string description: The ordering company's account. clientSubAccount: type: string description: The ordering company's subaccount. clinicId: type: string description: The ID of the clinic. clinicName: type: string description: The name of the clinic that's performing the screening. clinicAddress1: type: string description: The clinic's address. clinicAddress2: type: string description: The clinic's address, continued. clinicCity: type: string description: The clinic's city. clinicState: type: string description: The clinic's state. clinicZip: type: string description: The clinic's zip code. clinicPhoneNumber: type: string description: The clinic's phone number. clinicFaxNumber: type: string description: The clinic's fax number. network: type: string description: The network coverage for the clinic. example: In Network Tier 1 firstName: type: string description: The candidate's first name. lastName: type: string description: The candidate's last name. birthDate: type: string description: The candidate's birth date. example: 01/21/1980 ssnLast4: type: string description: The last four digits of the candidate's Social Security number. source: type: string physicalID: type: string description: The service provider's ID for the physical exam. verificationType: type: string enum: - titer - physical - vaccination componentId: type: string description: The service provider's ID for the service. componentDescription: type: string description: The description for the service component. status: type: string description: The readable text for the status. result: type: string description: The readable text for the result. resultId: type: string description: The unique ID of the result for the service. resultCode: type: string description: The service provider's code for the result of the service. resultDate: type: string format: date-time example: '2024-06-14T00:34:00.000Z' description: The date and time when the service was performed. For example, when the titer blood draw was performed or when actual immunity happened (via testimony). resultDueToReason: type: string description: The reason for the result. A reason is not always provided. resultExpirationDate: type: string description: The date the certified result expires. An expiration date is not always provided. resultStatusDescription: type: string description: The description for the result. partialReasons: type: array description: Reasons for a Partial status. items: type: string examDate: type: string example: 6/14/2024 description: The date of the exam. followUpDate: type: string description: The follow-up date, if applicable. certExpirationDate: type: string tbReadDate: type: string description: The date the TB test was read, if available. comments: type: string description: Comments from the exam. clientAddress1: type: string description: The ordering company's street address. clientAddress2: type: string description: The ordering company's street address, continued. clientCity: type: string description: The ordering company's city. clientContact: type: string description: The ordering company's contact. clientState: type: string description: The ordering company's state. clientZip: type: string description: The ordering company's zip code. collectionSitePhoneNumber: type: string description: The collection site's phone number. dlClass: type: string description: The driver's license class. dlNumber: type: string description: The driver's license number. dlStateCode: type: string description: The driver's license state code. cdlFlag: type: string description: 'A boolean integer: 1 (true) if the driver''s license is a commercial driver''s license; 0 (false) otherwise.' nrcmeNumber: type: string description: The 10-digit National Registry certification number from the DOT. otherID: type: string description: An alternate form of identification. otherIDType: type: string description: The type of alternate identification {id,name,value}. overallStatusDescription: type: string description: The description of the overall status of the physical exam. physicalReasonDescription: type: string description: The description of the reason for the physical exam. additionalInfo: type: string CaseOrderDataDocumentProcessing: title: CaseOrderDataDocumentProcessing type: object required: - documentTypeId - fileName - secureDocumentId properties: documentTypeId: type: string enum: - unclassified description: The identifier of the document type for the document to be processed. For the document processing flow this should always be `unclassified`. fileName: type: string description: The name of the file. example: sample-file-1.pdf secureDocumentId: type: string description: The identifier for the secureDocumentRecord the document is associated with. example: b7e2c1a2-1234-4f8b-9e2a-abcdef123456 CaseResultID: title: CaseResultID type: string description: 'The ID of the result for the case. See [Case-level result and statuses](docs/reference/case-status.md) for more details about each possible result. - Open: 8c94f0d9-57c9-4c7b-be95-5ec309cff330 - Placed: bbbd9fa2-598f-43f6-8363-b8b55e7aa777 - Pre-Adverse Action: 14bba02d-e6c7-45bf-a993-e28c306303c6 - Dispute Adverse Action: result-type-dispute-adverse - Adverse Action: d082a629-5dff-4303-83ae-897776ebcb17' enum: - 8c94f0d9-57c9-4c7b-be95-5ec309cff330 - bbbd9fa2-598f-43f6-8363-b8b55e7aa777 - 14bba02d-e6c7-45bf-a993-e28c306303c6 - result-type-dispute-adverse - d082a629-5dff-4303-83ae-897776ebcb17 ServiceCategoryId: title: ServiceCategoryId type: string description: The unique ID of the service category. enum: - service-cat-payment - service-cat-idv - service-cat-criminal - service-cat-mvr - service-cat-verification - service-cat-ohs - service-cat-pro-lic CaseStatusID: title: CaseStatusID type: string enum: - d894b8a0-937e-46b1-8799-15bad611844f - 93827364-937e-46b1-8799-777366485997 - 22334455-937e-46b1-8799-887766554433 - 47463524-937e-46b1-8799-873f63e7b402 description: 'The ID for the primary status of a case. See [Case-level result and statuses](docs/reference/case-status.md) for more details about each possible status. - Pending (in progress): d894b8a0-937e-46b1-8799-15bad611844f - Blocked (blocked): 93827364-937e-46b1-8799-777366485997 - Complete (done): 22334455-937e-46b1-8799-887766554433 - Adjudicated (decision made): 47463524-937e-46b1-8799-873f63e7b402' CaseOrderDataGovtID: title: CaseOrderDataGovtID type: object description: The candidate data when `caseOrderDataTypeId` is `codt-govt-id`. required: - govtId properties: govtId: type: string example: 111-22-3333 description: The candidate's Social Security number in the format *xxx*-*xx*-*xxxx*. pattern: ^\d{3}-\d{2}-\d{4}$ DetailsSexOffender: title: DetailsSexOffender type: object examples: - dateCompleted: '2024-06-17T19:51:30.985+00:00' timeToComplete: instant records: - charge: COMMUNICATION WITH MINOR FOR IMMORAL PURPOSES offenseType: FELONY dispositionDate: '2019-07-02' disposition: GUILTY caseNumber: PD 1234567.9876543 FG comments: 'Provider: Washington Sex Offender Registry' contextualData: 'charge=COMMUNICATION WITH MINOR FOR IMMORAL PURPOSES offenseType=FELONY comments=Provider: Washington Sex Offender Registry' description: Details from a sex offender search. properties: dateCompleted: type: string format: date-time example: '2024-06-17T19:51:30.985+00:00' timeToComplete: type: string example: instant additionalInfo: type: string records: type: array items: type: object properties: charge: type: string offenseType: type: string dispositionDate: type: string format: date example: '2015-08-21' disposition: type: string caseNumber: type: string comments: type: string contextualData: type: string ConfigValuesEmploymentVerification: title: ConfigValuesEmploymentVerification type: string enum: - docs-acceptable - psv - psv-first description: The configuration options for employment verification. default: docs-acceptable ConfigValuesQuantiferon: title: ConfigValuesQuantiferon type: string enum: - company-default - replace-with-t-spot - do-not-replace description: The options for Quantiferon substitution. default: company-default DetailsIdentity: title: DetailsIdentity type: object examples: - dateCompleted: 1712703321520 timeToComplete: instant additionalInfo: '' serviceId: service-idv-id-liveliness verificationAttempts: - verificationResult: passed idvProviderRefId: D3CC823DF4293926C29DDBD72F8DD2E7 idvProvider: Identity Provider adjudicator: system completionStamp: 1712703321520 images: - imageType: drivers_license secureImageId: c872f431-e9e9-3c82-8896-8dd0a53d029d - imageType: liveliness secureImageId: d66b0fc8-a171-4a1b-8ad0-a6cb4aa49534 - imageType: signature secureImageId: 9f6391e3-4d76-4011-bc11-8dd0a53d029d - imageType: id_thumbnail secureImageId: 946f932e-4703-4ddb-9660-8eba53edf337 description: Details from an identity verification. properties: dateCompleted: type: number example: 1712703321520 timeToComplete: type: string example: instant additionalInfo: type: string serviceId: type: string enum: - service-idv-id - service-idv-id-liveliness verificationAttempts: type: array description: A list of verification attempts, with the most recent listed first. items: type: object properties: verificationResult: type: string enum: - not_verified - passed - failed - manual_pass - manual_fail adjudicationComments: type: string description: Comments regarding a manual verification. idvProviderRefId: type: string idvProvider: type: string adjudicator: type: string enum: - system - manual description: Null if `verificationResult` is `not_verified`. completionStamp: type: number description: Null if `verificationResult` is `not_verified`. example: 1712703321520 images: type: array description: Null if `verificationResult` is `not_verified`. items: type: object properties: imageType: type: string enum: - drivers_license - id_thumbnail - liveliness - signature secureImageId: type: string format: uuid EducationEmploymentReceivedResults: title: EducationEmploymentReceivedResults enum: - pending - 'yes' - 'no' - notperformed readOnly: true description: An indicator of whether data was obtained for the service. This does not indicate good or bad data. CaseOrderDataShipment: title: CaseOrderDataShipment type: object description: The candidate data when `caseOrderDataTypeId` is `codt-shipment`. examples: - recipientName: John Smith address1: 1952 Whitney Avenue address2: Unit 2 addressType: home addressSource: homeAddress city: Hamden state: CT postalCode: '06517' shippingMethod: Overnight maskType: Honeywell DC365 N95 - recipientName: John Smith c/o KC Clinic address1: 1952 Whitney Avenue addressType: clinic city: Hamden state: CT postalCode: '06517' shippingMethod: Overnight maskType: Honeywell DC365 N95 required: - recipientName - address1 - addressType - city - state - postalCode - shippingMethod - maskType properties: recipientName: type: string description: The recipient name. address1: type: string description: The recipient's street address. address2: type: string description: The recipient's street address, continued. addressType: enum: - home - clinic description: The address type. addressSource: enum: - homeAddress - newAddress description: The source of the address, which indicates whether the address is the same as the candidate's home address. This is used only when `addressType` is `home`. city: type: string description: The recipient's city. state: type: string description: The two-letter state code. postalCode: type: string description: The recipient's zip code. shippingMethod: description: The shipping method. enum: - 2-3 Business Days - Overnight maskType: type: string description: The mask SKU from [GET `/shipment/mask/list`](karma-api-openapi.yaml/paths/~1shipment~1mask~1list/get). DetailsCPLC: title: DetailsCPLC type: object description: Details from a Professional License and Certification verification. examples: - dateCompleted: '2024-05-17T21:14:30.846Z' timeToComplete: instant comments: '' serviceContext: cplcId: cb3dac22-db86-44df-8193-877559b3e8dc fields: - fieldId: licenseNumber value: 987654RN - fieldId: firstName value: Yuri - fieldId: lastName value: Smith - fieldId: state value: CA licStatus: UNENCUMBERED issueDate: '2001-08-10' expirationDate: '2024-06-30' flagged: false additionalInfo: ' Active: YES Compact Status: N/A' source: nursys rawDataType: json rawDataKey: dd123c6b-1111-1111-9eb7-1e7349b56691 properties: dateCompleted: type: string format: date-time example: '2024-05-17T21:14:30.846Z' timeToComplete: type: string example: instant comments: type: string serviceContext: type: object properties: cplcId: description: The unique ID of the professional license or certification. See [Professional license and certification](docs/reference/cplc.md) for details about the possible values. type: string fields: type: array items: type: object properties: fieldId: type: string value: type: string licStatus: type: string issueDate: type: string format: date example: '2001-08-10' expirationDate: type: string format: date example: '2024-06-30' flagged: type: boolean additionalInfo: type: string description: Always empty, except for nursys. source: type: string rawDataType: type: string example: json rawDataKey: type: string description: The S3 key to the raw data. ServiceSubCategory: title: ServiceSubCategory type: string description: The subcategory that a service belongs to. enum: - Drug Screening - TB - Titer - Vaccination - Physical JurisdictionsFederalDistrictCourtAndCounty: title: JurisdictionsFederalDistrictCourtAndCounty type: object description: Federal district court and county entity. required: - name - stateCode - state properties: name: type: string district: type: string stateCode: type: string description: The two-letter code for the state. state: type: string county: type: string LegalAcknowledgmentSignature: title: LegalAcknowledgmentSignature type: object required: - signatureType - signature properties: signatureType: type: string enum: - electronic - manual signature: type: string description: For candidates who onboarded using KarmaCheck's onboarding experience, the value that the candidate entered into the signature input field on the legal step. This might not be exactly the same as the name that the case was ordered under. DetailsInternational: title: DetailsInternational type: object description: Details from international screenings. properties: externalId: type: string format: uuid description: The service provider's ID for the candidate. source: type: string example: certn dateCompleted: type: string format: date-time example: '2024-06-11T23:02:23.156090Z' description: The date when the service was completed. timeToComplete: type: string example: instant description: The amount of time it took to complete the service. additionalInfo: type: string CaseDataPendingStatusID: title: CaseDataPendingStatusID type: string enum: - drugtest-appointment-scheduled - drugtest-appointment-change - drugtest-appointment-canceled - drugtest-appointment-requested - drugtest-sent - drugtest-received - drugtest-review - drugtest-pending - drugtest-expired - pending-status-scheduled - pending-status-rescheduled - pending-status-canceled - pending-status-requested - pending-status-pending - pending-status-no-show - pending-status-partial - pending-status-refusal - pending-status-suspended - pending-status-medical-review - pending-status-not-performed description: The ID of the pending status for the service. See [Case data statuses](docs/reference/case-data-status.md) for more details. ConfigEmpIncomeVerification: title: EmploymentIncomeVerification type: object description: The configuration for employment income verification. required: - verificationMethod properties: verificationMethod: type: object description: The verification method that's configured for the screening. required: - rawValue - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The configuration setting that specifies acceptable forms of verification. pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Documents acceptable. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies the verification method used for this service. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Documents Acceptable configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Verification Method ConfigEmpVerification: title: EmploymentVerification type: object description: The configuration for employment verification. required: - verificationMethod properties: verificationMethod: type: object description: The verification method that's configured for the screening. required: - rawValue - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The configuration setting that specifies acceptable forms of verification. pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Documents acceptable. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies the verification method used for this service. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Documents Acceptable configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Verification Method ConfigTspot: title: Tspot type: object description: The configuration for T-Spot testing. required: - substitutionPolicy properties: substitutionPolicy: type: object description: The substitution policy that's configured for the test. required: - rawValue - pillLabel - valueDescription - configDescription - valueDisplayLabel - configDisplayLabel properties: rawValue: $ref: '#/components/schemas/ConfigValuesTspot' description: The configuration setting that specifies whether the test can be replaced. pillLabel: type: string description: The label that's displayed to KarmaCheck dashboard users to indicate the configuration setting for the screening. example: ${value} valueDescription: type: string description: A description of the configuration setting. example: Refer to company settings. configDescription: type: string description: A description that explains what the configuration does. This description is displayed to KarmaCheck dashboard users. example: Specifies if Quantiferon Gold can be ordered in place of T-Spot when T-Spot is unavailable. valueDisplayLabel: type: string description: A description of the configuration setting that's displayed to KarmaCheck dashboard users. example: Refer To Company Settings configDisplayLabel: type: string description: The configuration label that's displayed to KarmaCheck dashboard users. example: Substitution Policy AdverseActionStatusID: title: AdverseActionStatusID type: string enum: - bb34dc52-4e3b-4baf-8e0b-b6603f9e2a84 - ebbcb8e0-a0e7-43fb-930e-e52db4032d47 - d61950cb-00aa-4839-9da5-0c97f236c813 - fb32cc36-7eb6-47fa-ad4a-2635e99f197a description: 'The status ID of an adverse action on a candidate. - Pre-Adverse: bb34dc52-4e3b-4baf-8e0b-b6603f9e2a84 - Dispute: ebbcb8e0-a0e7-43fb-930e-e52db4032d47 - Cancel: d61950cb-00aa-4839-9da5-0c97f236c813 - Post: fb32cc36-7eb6-47fa-ad4a-2635e99f197a ' EducationVerificationIndividualRecordStatus: title: EducationVerificationIndividualRecordStatus description: "The status ID of an individual education record's status in the context of an Education Verification case data record.\n\n- acknowledge (done positive): 1a8490cb-084d-4209-bf2f-d46e41d760d6\n- consider (done and needs review): f657c777-c38d-489b-ac26-dd9bf0a88724 \n- pending (in progress): 8f29e0de-10f2-4c84-8379-16c6eb7cdf64" type: string enum: - 1a8490cb-084d-4209-bf2f-d46e41d760d6 - f657c777-c38d-489b-ac26-dd9bf0a88724 - 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 InvitationStatus: title: InvitationStatus type: string enum: - pending - expired - completed - cancelled description: The status of onboarding invitation to a candidate. LegalAcknowledgmentDisclosures: title: LegalAcknowledgmentDisclosures type: object required: - sendReport - list properties: sendReport: type: boolean description: If true, a report notification will be emailed to the candidate when the report is finished. list: type: array items: type: object required: - legalType properties: legalType: $ref: '#/components/schemas/LegalType' description: The type of legal disclosure. This is the value returned after calling [Request location-specific disclosures](karma-api-openapi.yaml/paths/~1case~1id~1{caseId}~1{disclosureType}~1{language}/post). signature: type: string description: The value that the candidate entered into the signature input field on the legal step. Required if `legalType` is `general-*` or `custom-*`; not required for other types of legal disclosures. CaseSummary: title: CaseSummary type: object examples: - id: f252d717-9bc8-4d21-85b4-5fd29645226a crStamp: '2024-04-05T19:21:27.000+00:00' crUserId: fed29350-84f3-4d35-9df1-9a73f14d9d17 caseTypeId: cde61186-4f22-45f4-9e19-429061365bce caseType: Background Check caseStatusId: 47463524-937e-46b1-8799-873f63e7b402 caseStatus: Adjudicated resultType: Placed modStamp: '2024-04-06T00:03:15.000+00:00' candidateId: 283de3e9-f12e-2184-9ac4-6e783e85b0de candidateEmail: charlie@example.com candidateGivenName: Charlie candidateFamilyName: Williams packageName: Basic Check packageId: f23fdee1-2ea5-23fc-9832-293a5d23a08b billingReferenceId: d64fddc1-1fa5-23fc-9832-231a5d23a08b groupProfileId: de0546f4-ad22-4c76-db12-06ae7e372fd2 groupName: Default resultTypeId: bbbd9fa2-598f-43f6-8363-b8b55e7aa777 caseInvitationId: 23cbf4ea-a174-47b0-9bc8-1273619a121b invitationGivenName: Charlie invitationFamilyName: Williams invitationStatusId: d1962405-dd97-48f2-bede-530c2895481f invitationStatusName: completed companyId: ded9edfd-292b-19f8-bdd4-f9bb001eba2c companyName: Example Company serviceGroupId: b2322ef5-72d7-4f28-9973-858464f01141 invitationEmail: charlie@example.com isMinorCandidate: 0 hasParentalConsent: 0 isCustomerProvidedPii: 1 archived: 0 orderedStamp: '2024-04-05T19:21:27.000+00:00' completedOnboardingStamp: '2024-04-05T19:21:27.000+00:00' beginProcessingStamp: '2024-04-05T19:21:29.000+00:00' completedInitialProcessingStamp: '2024-04-06T00:02:29.000+00:00' completedLatestProcessingStamp: '2024-04-06T00:02:29.000+00:00' companyReadableName: Example Company required: - id - crStamp - crUserId - caseTypeId - caseType - caseStatusId - caseStatus - resultType - modStamp - packageName - packageId - groupProfileId - groupName - resultTypeId - caseInvitationId - companyId - companyName - invitationEmail - isMinorCandidate - hasParentalConsent - isCustomerProvidedPii - archived - orderedStamp - companyReadableName properties: id: type: string description: The unique identifier of the case. crStamp: type: string format: date-time example: '2024-05-23T17:21:07.000+00:00' crUserId: type: string caseTypeId: type: string enum: - cde61186-4f22-45f4-9e19-429061365bce caseType: type: string enum: - Background Check caseStatusId: $ref: '#/components/schemas/CaseStatusID' caseStatus: $ref: '#/components/schemas/CaseStatus' secondaryCaseStatusId: $ref: '#/components/schemas/CaseSecondaryStatusID' secondaryStatus: $ref: '#/components/schemas/CaseSecondaryStatus' resultType: $ref: '#/components/schemas/CaseResult' modStamp: type: string format: date-time example: '2024-06-04T19:19:39.000+00:00' candidateId: type: string candidateEmail: type: string candidateGivenName: type: string candidateFamilyName: type: string packageName: type: string packageId: type: string packageCompanyName: type: string billingReferenceId: type: string groupProfileId: type: string groupName: type: string resultTypeId: $ref: '#/components/schemas/CaseResultID' caseInvitationId: type: string invitationGivenName: type: string invitationFamilyName: type: string invitationStatusId: $ref: '#/components/schemas/InvitationStatusID' invitationStatusName: $ref: '#/components/schemas/InvitationStatus' companyId: type: string companyName: type: string companyCommonName: type: string companyLogo: type: string serviceGroupId: type: string invitationEmail: type: string isMinorCandidate: type: integer description: 'A boolean integer: 1 (true) if the candidate is a minor; 0 (false) otherwise.' hasParentalConsent: type: integer description: 'A boolean integer: 1 (true) if the candidate is a minor and parental consent has been provided; 0 (false) otherwise.' isCustomerProvidedPii: type: integer description: 'A boolean integer: 1 (true) if the case was ordered using the customer-provided PII flow; 0 (false) otherwise.' archived: type: integer description: 'A boolean integer: 1 (true) if the case is archived; 0 (false) otherwise.' adverseActionId: type: string adverseActionStatusName: $ref: '#/components/schemas/AdverseActionStatusName' adverseActionStatusId: $ref: '#/components/schemas/AdverseActionStatusID' apiTrackingCode: type: string apiTrackingUser: type: string orderedStamp: type: string format: date-time example: '2024-05-23T17:21:07.000+00:00' beginOnboardingStamp: type: string format: date-time example: '2024-05-23T17:21:07.000+00:00' completedOnboardingStamp: type: string format: date-time example: '2024-05-23T17:21:08.000+00:00' beginProcessingStamp: type: string format: date-time example: '2024-05-23T17:21:08.000+00:00' completedInitialProcessingStamp: type: string format: date-time example: '2024-05-23T17:21:12.000+00:00' completedLatestProcessingStamp: type: string format: date-time example: '2024-05-23T17:21:12.000+00:00' companyReadableName: type: string CaseStatus: title: CaseStatus type: string enum: - Pending - Blocked - Complete - Adjudicated LegalType: title: LegalType type: string enum: - general-all-disclosure - general-ca-disclosure - state-city-all-disclosure - custom-ab-disclosure-1 - custom-ab-ca-disclosure-1 - custom-ab-disclosure-2 - custom-ab-ca-disclosure-2 - custom-dynamic-all-disclosure - custom-dynamic-ca-disclosure description: The type of legal disclosure. DetailsStateCriminalDatabase: title: DetailsStateCriminalDatabase type: object description: Details from a state criminal search. examples: - serviceId: d9381240-6230-40ec-9e11-35703e8041bc dateCompleted: '2024-05-17T19:47:14.885+00:00' timeToComplete: 2 days records: - state: AZ AOC charge: OPEN CONTAINER OF LIQUOR W/IN VEH offenseType: MISDEMEANOR disposition: PLEA GUILTY/RESP SENT IMPOSED dispositionDate: '2019-07-09' caseNumber: M-0000-3583999 comments: 'Case#: M-0000-3583999 Court: Phoenix Municipal' jurisdiction: AZ AOC fileDate: '2019-07-10' contextualData: state=AZ AOC jurisdiction=AZ AOC properties: serviceId: type: string enum: - d9381240-6230-40ec-9e11-35703e8041bc dateCompleted: type: string format: date-time example: '2024-05-17T19:47:14.885+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string records: type: array description: Records found from the criminal search. items: type: object properties: state: type: string example: AZ AOC charge: type: string example: SELLING ALCOHOL TO MINOR; MINOR IN POSSE offenseType: type: string example: MISDEMEANOR disposition: type: string example: PLEA GUILTY/RESP SENT IMPOSED dispositionDate: type: string format: date example: '2019-07-26' caseNumber: type: string example: M-0000-1234567 comments: type: string example: 'Case#: M-0000-1234567 Court: Phoenix Municipal' jurisdiction: type: string example: AZ AOC fileDate: type: string format: date example: '2019-07-16' contextualData: type: string CreateCase: title: CreateCase type: object required: - packageId - email - givenName - familyName properties: autoProcess: type: boolean default: false description: If true, the customer is providing all of the information needed to run the check up front; other fields in the payload will be required. If false, the candidate will receive an onboarding invitation to provide the remaining data needed for the check. caseTypeId: type: string enum: - cde61186-4f22-45f4-9e19-429061365bce default: cde61186-4f22-45f4-9e19-429061365bce description: The API currently supports only one type of case, which is a background check. packageId: type: string description: The ID of the package to order for the case. See [Get package list](karma-api-openapi.yaml/paths/~1package~1min~1list/get) to retrieve the list of available packages. email: type: string description: The candidate's email address. givenName: type: string description: The candidate's first name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. middleName: type: string description: The candidate's middle name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. familyName: type: string description: The candidate's last name. Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. phone: type: string description: If `autoProcess` is true and OHS services exist in the package, a phone number in the format **+[country_code][phone_number]** is required (whether or not any OHS services are being ordered). If `autoProcess` is false, this field is optional. example: '+18005550145' apiTrackingUser: type: string description: "An external identifier that you can use \nto help track this case in your own system.\n\nKarmaCheck does not do anything with this field other than include it in webhooks and other API calls,\nso despite its name, you can put any value.\n\nA common use case is for the value to be\nthe email address of the user in your system\nwho ordered the case." apiTrackingCode: type: string description: "An external identifier that you can use \nto help track this case in your own system.\n\nKarmaCheck does not do anything with this field other than include it in webhooks and other API calls,\nso despite its name, you can put any value.\n\nA common use case is for the value to be\nthe identifier of the case in your system." disableOptions: type: integer description: 'A parameter to control how KarmaCheck sends email notifications about the case. By default, KarmaCheck sends an email notifying the candidate when a background check is initiated. Email notifications are standard, as further communication with the candidate might be necessary. To prevent certain emails from being sent, use the following values to disable emails to the candidate or customer: - **1:** Prevents sending invite to the candidate - **2:** Prevents sending updates to the candidate - **4:** Prevents sending notifications to the customer - **7:** Disables all email notifications described above' excludeServices: type: array description: If the order should not run one or more services that are defined in the package, then list the IDs of each service. Not all services support exclusion; for example, legal authorizations and SSN Trace are needed for other services being ordered. items: type: string orderOverride: type: - string - 'null' default: null enum: - add - replace - null description: "Indicates how to handle an active case that exists for the same candidate email:\n- Use `add` to create a new case anyway. \n- Use `replace` to archive the existing case and create a new case.\nWithout this field, calling the API returns an error if a case already exists." replaceCaseId: type: string description: The ID of the existing case to replace. Required if `orderOverride` is `replace`. candidateConsentProvided: type: boolean description: If true, acknowledges collection of the candidate's signed disclosures and authorizations. This must be set to true if `autoProcess` is true. candidateDisclosuresAndAuthorizationDocumentIds: type: array description: A list of IDs for each [secure document](karma-api-openapi.yaml/paths/~1document~1secure~1create/post) to associate with the case. items: type: string orderData: type: array description: The candidate's PII and other required data based on the services being ordered. Required if `autoProcess` is true. Each service has different `metadata` properties based on the specified `caseOrderDataTypeId`. See [Provide order data](docs/guides/order-data.md) for additional details. items: $ref: '#/components/schemas/CaseOrderData' orderConfig: $ref: '#/components/schemas/OrderConfig' ConfigValuesTspot: title: ConfigValuesTspot type: string enum: - company-default - replace-with-quantiferon - do-not-replace description: The options for T-Spot substitution. default: company-default ServiceConfigs: title: ServiceConfigs description: Services with configuration options. type: object properties: 85307784-1f84-471a-8596-c8ea088c3a62: $ref: '#/components/schemas/ConfigEduVerification' 9ac65633-b4c4-4062-875c-3556db9d2a08: $ref: '#/components/schemas/ConfigEmpVerification' service-employment-income: $ref: '#/components/schemas/ConfigEmpIncomeVerification' service-ohs-tb-quantiferon-gold: $ref: '#/components/schemas/ConfigQuantiferon' service-ohs-tb-tspot-test: $ref: '#/components/schemas/ConfigTspot' CaseOrderDataDrugTestingAuthority: title: CaseOrderDataDrugTestingAuthority type: object description: The regulatory authority under which a DOT drug test is conducted. examples: - testingAuthority: fmcsa properties: testingAuthority: type: string enum: - fmcsa - faa - fra - fta - phmsa - uscg description: The regulatory authority under which a DOT drug test is conducted. Defaults to `fmcsa` if not provided. default: fmcsa CaseDataStatus: title: CaseDataStatus description: The possible statuses of a case data record (an instance of a service). type: string enum: - acknowledge - clear - consider - not_found - canceled - complete - pending - error DetailsEmployment: title: DetailsEmployment type: object examples: - dateCompleted: '2024-05-17T20:16:30.846+00:00' timeToComplete: 6 days records: - statusId: 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 - statusId: 1a8490cb-084d-4209-bf2f-d46e41d760d6 employer: Employer B location: Washington, D.C. receivedResults: 'yes' applicantProvided: position: Nurse dateSpan: 2000 - 10 to 2003 - 10 institutionProvided: position: Nurse dateSpan: 2000 - 10 to 2003 - 10 testimonyId: f3dd7129-e553-4870-b99e-472de8d6c522 description: Details from an employment verification. properties: dateCompleted: type: string format: date-time example: '2024-05-17T20:16:30.846+00:00' timeToComplete: type: string example: 6 days additionalInfo: type: string records: type: array items: type: object properties: statusId: $ref: '#/components/schemas/EmploymentVerificationIndividualRecordStatus' employer: type: string location: type: string receivedResults: $ref: '#/components/schemas/EducationEmploymentReceivedResults' applicantProvided: type: object properties: position: type: string salary: type: string dateSpan: type: string example: 2000 - 10 to 2003 - 10 additionalInfo: type: string institutionProvided: type: object properties: position: type: string salary: type: string dateSpan: type: string example: 2000 - 10 to 2003 - 10 additionalInfo: type: string testimonyId: type: string description: Associated testimony identifier searchId: type: string description: Associated case data search identifier DetailsMaskShipment: title: DetailsMaskShipment description: Details of a mask shipment. allOf: - $ref: '#/components/schemas/CaseOrderDataShipment' - type: object properties: trackingNumber: type: string example: 1ZE660080325370038 courier: type: string example: UPS dateCompleted: type: string format: date-time example: '2024-07-16T20:20:15.196Z' timeToComplete: type: string example: 5 days additionalInfo: type: string examples: - recipientName: John Smith address1: 1952 Whitney Avenue address2: Unit 2 addressType: home addressSource: homeAddress city: Hamden state: CT postalCode: '06517' shippingMethod: Overnight maskType: Honeywell DC365 N95 trackingNumber: 1ZE660080325370038 courier: UPS dateCompleted: '2024-07-16T20:20:15.196Z' timeToComplete: 5 days additionalInfo: '' Contact: title: Contact type: object description: Details of a contact. examples: - name: Dana R. type: default email: defaultcontact@example.com phone: 800-555-0150 - name: Alex P. type: escalation email: escalationcontact@example.com required: - type - email properties: name: type: string maxLength: 255 description: The name of the contact. type: type: string enum: - default - escalation - authorization description: The role of the contact. email: type: string description: The email address of the contact. format: email phone: type: string maxLength: 20 description: The phone number of the contact. EmploymentVerificationIndividualRecordStatus: title: EmploymentVerificationIndividualRecordStatus description: "The status ID of an individual employment record's status in the context of an Employment Verification case data record.\n\n- acknowledge (done positive): 1a8490cb-084d-4209-bf2f-d46e41d760d6\n- consider (done and needs review): f657c777-c38d-489b-ac26-dd9bf0a88724 \n- pending (in progress): 8f29e0de-10f2-4c84-8379-16c6eb7cdf64" type: string enum: - 1a8490cb-084d-4209-bf2f-d46e41d760d6 - f657c777-c38d-489b-ac26-dd9bf0a88724 - 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 CaseSecondaryStatusID: title: CaseSecondaryStatusID type: string enum: - 8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea - c5f240cb-5221-451c-8bd1-4be5bf348ce5 - b2c707af-091f-4d07-9546-4a1453f939e5 - status-type-verifying-cand-input - status-type-reviewing-order - status-type-consider - 4155584b-708c-4108-86a8-8f3321b9b17c description: 'The ID for the secondary status of a case. See [Case-level result and statuses](docs/reference/case-status.md) for more details about each possible status. - Waiting for Authorization: 8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea - Authorization in Progress: c5f240cb-5221-451c-8bd1-4be5bf348ce5 - Waiting for Parental Consent: b2c707af-091f-4d07-9546-4a1453f939e5 - Verifying Candidate PII Input: status-type-verifying-cand-input - Reviewing Order: status-type-reviewing-order - Consider (completed needs review): status-type-consider - Canceled: 4155584b-708c-4108-86a8-8f3321b9b17c ' Configuration: title: Configuration type: object properties: contacts: type: array description: A list of people to contact about the case. items: $ref: '#/components/schemas/Contact' serviceConfigs: $ref: '#/components/schemas/ServiceConfigs' diluteDrugPolicy: $ref: '#/components/schemas/ConfigDiluteDrug' aliasNameConfiguration: $ref: '#/components/schemas/ConfigAliasName' lostOrIncompleteOHSDrugPolicy: $ref: '#/components/schemas/ConfigLostOrIncompleteOHSDrug' ohsDrugPassportExpirationPolicy: $ref: '#/components/schemas/ConfigOhsDrugPassportExpiration' description: The [configuration](docs/reference/order-configuration.md) for a case or package. DetailsMotorVehicle: title: DetailsMotorVehicle type: object examples: - dateCompleted: '2024-06-17T19:56:43.925+00:00' timeToComplete: 2 days records: - state: CALIFORNIA licenseNumber: E78904321 issueDate: '2022-04-22' expirationDate: '2026-04-22' licenseClass: C classDescription: REGULAR LICENSE type: PERSONAL status: VALID fullName: WILLIAMS, JACK events: - state: CA eventType: Violation description: SPEEDING INTERMEDIATE (11-19 OVER) eventDate: '2022-05-24' convictionDate: '2022-06-13' disposition: GUILTY stateCode: 346.57(5) acd: S92 avd1: SA10 avd2: SA10 avd3: SA10 location: LOS ANGELES CITY MUNICIPAL COURT - WESTWOOD commercial: false hazMat: false - state: CA eventType: Suspension description: FAILURE TO PAY FORFEITURE eventDate: '2022-08-22' clearDate: '2023-05-15' stateCode: FPF acd: D53 avd1: DE12 avd2: DE12 avd3: DE12 commercial: false hazMat: false contextualData: state=CALIFORNIA licenseNumber=E78904321 fullName=WILLIAMS, JACK hasResults: true description: Details from a motor vehicle records check. properties: dateCompleted: type: string format: date-time example: '2024-06-17T19:56:43.925+00:00' timeToComplete: type: string example: 2 days additionalInfo: type: string records: type: array items: type: object properties: state: type: string licenseNumber: type: string issueDate: type: string format: date example: '2022-04-22' expirationDate: type: string format: date example: '2026-04-22' licenseClass: type: string classDescription: type: string type: type: string status: type: string fullName: type: string restrictions: type: array items: type: string endorsements: type: array items: type: string events: type: array items: type: object properties: state: type: string eventType: type: string enum: - Violation - Suspension - Disqualified description: type: string eventDate: type: string format: date example: '2015-04-12' offenseDate: type: string format: date example: '2015-04-12' description: If applicable. convictionDate: type: string format: date example: '2015-04-12' description: If applicable. clearDate: type: string format: date example: '2015-04-12' description: If applicable. disposition: type: string stateCode: type: string acd: type: string avd1: type: string description: If applicable. avd2: type: string description: If applicable. avd3: type: string description: If applicable. location: type: string commercial: type: boolean hazMat: type: boolean contextualData: type: string hasResults: type: boolean description: True if records were found; false otherwise. This does not indicate good or bad results. CaseOrderDataCandidateAddress: title: CaseOrderDataCandidateAddress type: object description: The order data (candidate's current home address) when `caseOrderDataTypeId` is `codt-current-candidate-address`. examples: - address1: 6 Flagstone Drive address2: Apartment 2 city: Hudson state: NH postalCode: '03051' country: US required: - address1 - city - state - postalCode - country properties: address1: type: string description: The candidate's street address. address2: type: string description: The candidate's street address, continued. city: type: string description: The candidate's city of residence. state: type: string description: The two-letter abbreviation of the state in which the candidate resides. postalCode: type: string description: The candidate's zip code. country: type: string description: The two-letter abbreviation of the country in which the candidate resides. CaseOrderDataJurisdictionState: title: CaseOrderDataJurisdictionState type: object description: The candidate data when `caseOrderDataTypeId` is `codt-jurisdiction-state`. required: - state properties: state: type: string description: The two-letter state code. example: NH DetailsOIG: title: DetailsOIG type: object examples: - result: no-exclusion-found input: givenName: Williams familyName: Jack govtId: 111-22-3333 dob: '1983-03-15' resultsPage: secureDocumentId: 5fee28bc-6dc4-42fc-2dcd-22c4a4858e71 nameMatchResults: [] dateCompleted: 1718649155997 timeToComplete: 2 days source: karmacheck additionalInfo: '' description: Details from an Office of Inspector General (OIG) exclusions search. properties: result: type: string enum: - no-exclusion-found - exclusion-found - no-exclusion-found-ops - exclusion-found-ops input: type: object properties: givenName: type: string familyName: type: string govtId: type: string example: 111-22-3333 dob: type: string format: date example: '1983-03-15' resultsPage: type: object properties: secureDocumentId: type: string format: uuid nameMatchResults: type: array items: type: object properties: secureDocumentId: type: string dobMatch: type: boolean ssnMatch: type: boolean dobMissing: type: boolean oigData: type: object properties: givenName: type: string middleName: type: string familyName: type: string dob: type: string npi: type: string upin: type: string general: type: string specialty: type: string street: type: string address: type: string exclType: type: string exclDate: type: string format: date example: '2020-01-15' waiver: type: string dateCompleted: type: number example: 1718649155997 timeToComplete: type: string example: 2 days source: type: string example: karmacheck additionalInfo: type: string CaseOrderDataJurisdictionCounty: title: CaseOrderDataJurisdictionCounty type: object description: The candidate data when `caseOrderDataTypeId` is `codt-jurisdiction-county`. required: - state - county properties: state: type: string description: The two-letter state code. example: NH county: type: string example: HILLSBOROUGH AdverseActionStatusName: title: AdverseActionStatusName type: string enum: - Pre-Adverse - Dispute - Cancel - Post CaseOrderDataMVR: title: CaseOrderDataMVR type: object description: The candidate data when `caseOrderDataTypeId` is `codt-mvr`. required: - state - licenseNumber properties: state: type: string description: The two-letter state code of the candidate's driver's license. licenseNumber: type: string description: The candidate's driver's license number. firstNameIfDifferent: type: string description: If the name on the driver's license is different than the candidate name entered for the case, the first name on the candidate's driver's license. middleInitialIfDifferent: type: string description: If the name on the driver's license is different than the candidate name entered for the case, the middle initial on the candidate's driver's license. lastNameIfDifferent: type: string description: If the name on the driver's license is different than the candidate name entered for the case, the last name on the candidate's driver's license. CaseOrderData: title: CaseOrderData type: object description: The data related to a service. Each service has different `metadata` properties based on the specified `caseOrderDataTypeId`. See [Provide order data](docs/guides/order-data.md) for additional details. required: - caseOrderDataTypeId - metadata properties: caseOrderDataTypeId: type: string enum: - codt-govt-id - codt-dob - codt-current-candidate-address - codt-ohs-scheduling-address - codt-education - codt-employment - codt-mvr - codt-alias - codt-address - codt-jurisdiction-county - codt-jurisdiction-fed-district - codt-jurisdiction-state - codt-cplc - codt-shipment - codt-ohs-service-substitutions - codt-idp - codt-drug-reason-for-test - codt-drug-testing-authority description: The type of data to include in the order. serviceId: type: string description: 'The ID of a [service](docs/reference/service.md) that requires a type of case order data. This field is required for the following case order data types: `codt-education` `codt-employment` `codt-mvr` `codt-alias` `codt-jurisdiction-county` `codt-jurisdiction-fed-district` `codt-jurisdiction-state` `service-cplc` `service-mask-shipment`' metadata: oneOf: - $ref: '#/components/schemas/CaseOrderDataGovtID' type: object - $ref: '#/components/schemas/CaseOrderDataDOB' type: object - $ref: '#/components/schemas/CaseOrderDataCandidateAddress' type: object - $ref: '#/components/schemas/CaseOrderDataOHSAddress' type: object - $ref: '#/components/schemas/CaseOrderDataEducation' type: object - $ref: '#/components/schemas/CaseOrderDataEmployment' type: object - $ref: '#/components/schemas/CaseOrderDataMVR' type: object - $ref: '#/components/schemas/CaseOrderDataAlias' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdiction' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionCounty' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionFederal' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionState' type: object - $ref: '#/components/schemas/CaseOrderDataCPLC' type: object - $ref: '#/components/schemas/CaseOrderDataShipment' type: object - $ref: '#/components/schemas/CaseOrderDataOHSServiceSubstitutions' - $ref: '#/components/schemas/CaseOrderDataDocumentProcessing' - $ref: '#/components/schemas/CaseOrderDataDrugReasonForTest' - $ref: '#/components/schemas/CaseOrderDataDrugTestingAuthority' securitySchemes: JWT: type: http scheme: bearer x-apievangelist-provenance: assembled: '2026-08-23' method: searched note: Reassembled verbatim from the 69 per-operation OpenAPI 3.1.0 YAML documents KarmaCheck publishes inside the markdown twins of its public API reference (https://developer.karmacheck.com/api-reference/.md). Each page embeds a complete, single-operation slice of KarmaCheck's own openapi.json; the 69 slices merged with ZERO conflicting definitions. No content was authored, inferred, or padded by API Evangelist. KarmaCheck's consolidated export at https://developer.karmacheck.com/background-check-api/api-reference/openapi.json is login-gated (HTTP 302 to /login), so this reassembly is the only machine-readable form of the contract reachable without credentials. source_index: https://developer.karmacheck.com/sitemap.xml slices_merged: 69 conflicts: 0