Provide order data - KarmaCheck

When you’re creating a case using the customer-provided PII flow, or adding to an existing order, you’ll need to provide the necessary candidate data. This data is sent in an orderData array of objects with the following properties:

Property	Type	Required	Description
`caseOrderDataTypeId`	`string`	`Required`	The type of candidate data to include in the order. See the Case order data types table for the possible types.
`serviceId`	`string`	—	The service for which the data is being provided. Required for certain case order data types.
`metadata`	`object`	`Required`	The candidate data. The exact properties are specific to each case order data type.

The types of order data to include depend on the services that are being ordered. At a minimum, the candidate’s government ID, date of birth, and current address need to be included as order data for a case:

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-govt-id",
      "metadata": {
        "govtId": "111-22-3333"
      }
    },
    {
      "caseOrderDataTypeId": "codt-dob",
      "metadata": {
        "dob": "1983-05-17"
      }
    },
    {
      "caseOrderDataTypeId": "codt-current-candidate-address",
      "metadata": {
        "address1": "100 Main St",
        "address2": "Unit 2",
        "city": "New York",
        "state": "NY",
        "postalCode": "10016",
        "country": "US"
      }
    }
  ]
}

The following sections describe each supported type of order data.

Case order data types

Case order data type	ID	Required?
Government ID	codt-govt-id	Yes. See Government ID for more details.
Date of birth	codt-dob	Yes. See Date of birth for more details.
Current candidate address	codt-current-candidate-address	Yes. See Current candidate address for more details.
Health screening scheduling address	codt-ohs-scheduling-address	Conditionally. See Health screening scheduling address for services that require this type of order data.
Education records	codt-education	Conditionally. See Education for services that require this type of order data.
Employment records	codt-employment	Conditionally. See Employment for services that require this type of order data.
Motor vehicle record (MVR)	codt-mvr	Conditionally. See Motor vehicle record for services that require this type of order data.
Alternative names for a candidate	codt-alias	No. See Aliases for services that support this type of order data.
Jurisdiction address	codt-address	No. See Jurisdictions for services that support this type of order data.
County jurisdiction	codt-jurisdiction-county	No. See Jurisdictions for services that support this type of order data.
Federal district jurisdiction	codt-jurisdiction-fed-district	No. See Jurisdictions for services that support this type of order data.
State jurisdiction	codt-jurisdiction-state	No. See Jurisdictions for services that support this type of order data.
Professional license and certification	codt-cplc	Conditionally. See Professional license and certification for services that require this type of order data.
Shipments	codt-shipment	Conditionally. See Shipments for services that require this type of order data.
Drug reason for test	codt-drug-reason-for-test	No. See Drug reason for test for services that support this type of order data.
Drug testing authority	codt-drug-testing-authority	No. See Drug testing authority for services that support this type of order data.

Case order data structures

Below are details and examples of each type of order data.

Government ID

The candidate’s government ID is always required in order data.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-govt-id",
      "metadata": {
        "govtId": "111-22-333"
      }
    }
  ]
}

metadata properties: govtId (string) — The candidate’s Social Security number in the format xxx-xx-xxxx. For testing purposes, use 111-22-3333.

Date of birth

The candidate’s birthdate is always required in order data.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-dob",
      "metadata": {
        "dob": "1983-05-17"
      }
    }
  ]
}

metadata properties: dob (string) — The candidate’s birthdate in the format yyyy-mm-dd.

Current candidate address

The candidate’s current address is always required in order data.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-current-candidate-address",
      "metadata": {
        "address1": "100 Main St",
        "address2": "Unit 2",
        "city": "New York",
        "state": "NY",
        "postalCode": "10016",
        "country": "US"
      }
    }
  ]
}

metadata properties: address1, address2, city, state (two-letter abbreviation), postalCode, country (two-letter abbreviation).

Health screening scheduling address

If an occupational health or drug screening is being ordered, you must provide an address that can be used for finding nearby clinics to fulfill the screening.

Service category	ID
Occupational health screening	service-cat-ohs

All OHS and drug screening services share the same serviceCategoryId (service-cat-ohs). If you’re running logic to determine if you need to include the codt-ohs-scheduling-address order data, you should use the serviceCategoryId in your conditional logic.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-ohs-scheduling-address",
      "metadata": {
        "address1": "100 Main St",
        "address2": "Unit 2",
        "city": "New York",
        "state": "NY",
        "postalCode": "10016",
        "country": "US"
      }
    }
  ]
}

Education

If Education Verification is being ordered, you must provide at least one education order data item.

Service	ID
Education Verification	85307784-1f84-471a-8596-c8ea088c3a62

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-education",
      "serviceId": "85307784-1f84-471a-8596-c8ea088c3a62",
      "metadata": {
        "institution": "Example University",
        "educationType": "College",
        "educationTypeDescription": "",
        "degree": "Bachelor of Science",
        "major": "Nursing",
        "city": "Manchester",
        "state": "NH",
        "country": "US",
        "monthBegin": "August",
        "yearBegin": "2000",
        "current": false,
        "monthEnd": "May",
        "yearEnd": "2004",
        "nameIfDifferentFlag": false,
        "nameIfDifferent": "",
        "contact": {
          "website": "exampleuniversity.edu",
          "email": "admin@exampleuniversity.edu",
          "phone": "800-555-0123"
        }
      }
    }
  ]
}

Employment

If an employment verification service is being ordered, you must provide at least one employment order data item.

Service	ID
Employment Verification	9ac65633-b4c4-4062-875c-3556db9d2a08
Employment Income Verification	service-employment-income

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-employment",
      "serviceId": "9ac65633-b4c4-4062-875c-3556db9d2a08",
      "metadata": {
        "employer": "Example Organization",
        "position": "Nurse",
        "city": "Manchester",
        "state": "NH",
        "country": "US",
        "monthBegin": "December",
        "yearBegin": "2004",
        "current": false,
        "monthEnd": "December",
        "yearEnd": "2018",
        "contact": {
          "website": "www.example.com",
          "email": "hr@example.com",
          "phone": "800-555-0147"
        },
        "okToContact": true
      }
    }
  ]
}

metadata properties: employer, position, city, state, country, monthBegin, yearBegin, current (boolean), monthEnd, yearEnd, contact.website, contact.email, contact.phone, okToContact (boolean), staffingAgency (optional, max 100 characters).

Motor vehicle record

If a Motor Vehicle Report is being ordered, you must provide at least one MVR order data item.

Service	ID
Motor Vehicle Report	9a1aa5db-1292-423e-a17c-4a7ab380de58

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-mvr",
      "serviceId": "9a1aa5db-1292-423e-a17c-4a7ab380de58",
      "metadata": {
        "state": "NH",
        "licenseNumber": "NHL12345678",
        "firstNameIfDifferent": "",
        "middleInitialIfDifferent": "",
        "lastNameIfDifferent": ""
      }
    }
  ]
}

Aliases

Alias order data is never required. This data is optional if you’re ordering one of the services that support aliases:

Service	ID
FACIS	2c6bbd00-dce3-4ecd-ae91-b0f3dab268f7
Global Watchlist Search	c3080270-3e83-4eb2-a2a9-e5964645f8c5
National Criminal Search	d8e3dbdb-c2d7-4787-9736-86fffab74da4
Federal Criminal Search	ee774b82-a411-4e2b-a38f-c0641bd836e7
State Criminal Court Search	c407f6dd-523e-4627-a4d9-8f52d30ee744
State Criminal Database Search	d9381240-6230-40ec-9e11-35703e8041bc
County Criminal Search	fa226cb7-1214-4cdf-9296-6120a7376926

When providing alias order data, you must do the following:

Include a master list of aliases for the candidate — one codt-alias item for each alias.
Include one codt-alias item for each service that you want verified using the alias. serviceId must be specified for these items.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-alias",
      "metadata": { "givenName": "Bill", "middleName": "", "familyName": "Moore" }
    },
    {
      "caseOrderDataTypeId": "codt-alias",
      "metadata": { "givenName": "Will", "middleName": "", "familyName": "Moore" }
    },
    {
      "caseOrderDataTypeId": "codt-alias",
      "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926",
      "metadata": { "givenName": "Bill", "middleName": "", "familyName": "Moore" }
    },
    {
      "caseOrderDataTypeId": "codt-alias",
      "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926",
      "metadata": { "givenName": "Will", "middleName": "", "familyName": "Moore" }
    }
  ]
}

Jurisdictions

Jurisdiction order data is never required. This data is optional if you’re ordering one of the jurisdiction-based services:

Service	ID
County Criminal Search	fa226cb7-1214-4cdf-9296-6120a7376926
Federal Criminal Search	ee774b82-a411-4e2b-a38f-c0641bd836e7
State Criminal Database Search	d9381240-6230-40ec-9e11-35703e8041bc
State Criminal Court Search	c407f6dd-523e-4627-a4d9-8f52d30ee744

The results of an SSN Trace will inform which jurisdictions to be searched. As a result, the final list of jurisdictions might be larger than the list that is provided as order data.

When providing jurisdiction order data, you must do the following:

Provide one or more addresses to derive the list of specific jurisdictions:

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-address",
      "metadata": {
        "city": "Manchester",
        "state": "NH",
        "county": "Hillsborough",
        "autoProcessJurisdictions": false
      }
    }
  ]
}

If autoProcessJurisdictions is set to false (or omitted), specify the jurisdictions for each relevant search type:

County jurisdictions:

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-jurisdiction-county",
      "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926",
      "metadata": { "state": "NH", "county": "HILLSBOROUGH" }
    }
  ]
}

Federal district jurisdictions:

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-jurisdiction-fed-district",
      "serviceId": "ee774b82-a411-4e2b-a38f-c0641bd836e7",
      "metadata": { "district": "New Hampshire District Court" }
    }
  ]
}

State jurisdictions:

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-jurisdiction-state",
      "serviceId": "c407f6dd-523e-4627-a4d9-8f52d30ee744",
      "metadata": { "state": "NH" }
    }
  ]
}

Use the POST /jurisdiction/find/all endpoint to help populate the specific jurisdiction order data. Setting autoProcessJurisdictions to true skips the need to specify individual jurisdiction items.

Professional license and certification

If a Professional License and Certification verification (CPLC) is being ordered, you must provide at least one CPLC order data item.

Service	ID
Professional License and Certification	service-cplc

To get the required fields for a specific license or certification:

Send a GET request to GET /service/cplc/list to retrieve all supported CPLCs and get the cplcId.
Send a GET request to GET /service/cplc/id/{cplcId} to retrieve the required fields for that cplcId.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-cplc",
      "serviceId": "service-cplc",
      "metadata": {
        "cplcId": "e9a5f173-a9cc-4dc7-91a0-25d5586b3d50",
        "fields": [
          { "fieldId": "licenseNumber", "value": "LN123456" },
          { "fieldId": "firstName", "value": "William" },
          { "fieldId": "lastName", "value": "Moore" },
          { "fieldId": "state", "value": "NH" }
        ]
      }
    }
  ]
}

Shipments

If a shipment service is being ordered, you must provide at least one shipment order data item regardless of PII flow. If you don’t include the order data when creating a case, the service will be excluded from the case order.

Service	ID
Mask Shipment	service-mask-shipment

To get the masks available for shipment:

Send a GET request to GET /shipment/mask/list to retrieve a list of masks.
In the returned list array, get the sku for a specific mask.

Only masks with inStock as true can be ordered. Attempting to order an out-of-stock mask results in a 422 response.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-shipment",
      "serviceId": "service-mask-shipment",
      "metadata": {
        "recipientName": "William Moore",
        "address1": "100 Main St",
        "address2": "Unit 2",
        "addressType": "home",
        "addressSource": "homeAddress",
        "city": "New York",
        "state": "NY",
        "postalCode": "10016",
        "shippingMethod": "2-3 Business Days",
        "maskType": "3M 8210"
      }
    }
  ]
}

Drug reason for test

If a DOT drug screening is being ordered, you can optionally provide a reason for test. If omitted, the default value of pre-employment is used.

Service category	ID
Occupational health screening	service-cat-ohs

Service sub-category	ID
Drug test	service-subcat-drug

Supported reasonForTest values:

Value	Description
`pre-employment`	Pre-employment screening (default).
`followup`	Follow-up screening.
`post-accident`	Post-accident screening.
`return-to-duty`	Return-to-duty screening.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-drug-reason-for-test",
      "metadata": {
        "reasonForTest": "pre-employment"
      }
    }
  ]
}

Drug testing authority

If a DOT drug screening is being ordered, you can optionally provide the regulatory authority under which the test is being conducted. If omitted, the default value of fmcsa is used.

Service category	ID
Occupational health screening	service-cat-ohs

Service sub-category	ID
Drug test	service-subcat-drug

Supported testingAuthority values:

Value	Description
`fmcsa`	Federal Motor Carrier Safety Administration (default).
`faa`	Federal Aviation Administration.
`fra`	Federal Railroad Administration.
`fta`	Federal Transit Administration.
`phmsa`	Pipeline and Hazardous Materials Safety Administration.
`uscg`	United States Coast Guard.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-drug-testing-authority",
      "metadata": {
        "testingAuthority": "fmcsa"
      }
    }
  ]
}

Document Processing

If document processing is being ordered, you must provide one codt-idp order data item per document to be processed. If you don’t provide order data for a document, it will not be included in the processing order.

Service	ID
Document Processing	service-intelligent-document-process

metadata properties:

Property	Description
`documentTypeId`	Document type identifier. Always use `unclassified` for Document Processing.
`fileName`	The file name as provided when uploading the document.
`secureDocumentId`	The secure document ID returned after creating the secure document record.

{
  "orderData": [
    {
      "caseOrderDataTypeId": "codt-idp",
      "serviceId": "service-intelligent-document-process",
      "metadata": {
        "documentTypeId": "unclassified",
        "fileName": "testfile1.pdf",
        "secureDocumentId": "e9a5f173-a9cc-4dc7-91a0-25d5586b3d50"
      }
    }
  ]
}

See the Document processing flow guide for a full walkthrough of uploading documents and creating a document processing order.

​Case order data types

​Case order data structures

​Government ID

​Date of birth

​Current candidate address

​Health screening scheduling address

​Education

​Employment

​Motor vehicle record

​Aliases

​Jurisdictions

​Professional license and certification

​Shipments

​Drug reason for test

​Drug testing authority

​Document Processing

Case order data types

Case order data structures

Government ID

Date of birth

Current candidate address

Health screening scheduling address

Education

Employment

Motor vehicle record

Aliases

Jurisdictions

Professional license and certification

Shipments

Drug reason for test

Drug testing authority

Document Processing