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

# Provide order data

> Reference for all supported orderData types when creating a case or adding to an order.

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                                                                                                                               |
| ----------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| <span style={{whiteSpace: "nowrap"}}>`caseOrderDataTypeId`</span> | `string` | `Required` | The type of candidate data to include in the order. See the [Case order data types](#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:

```json theme={null}
{
  "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](#government-id) for more details.                                                                                              |
| **Date of birth**                          | codt-dob                       | Yes. See [Date of birth](#date-of-birth) for more details.                                                                                              |
| **Current candidate address**              | codt-current-candidate-address | Yes. See [Current candidate address](#current-candidate-address) for more details.                                                                      |
| **Health screening scheduling address**    | codt-ohs-scheduling-address    | Conditionally. See [Health screening scheduling address](#health-screening-scheduling-address) for services that require this type of order data.       |
| **Education records**                      | codt-education                 | Conditionally. See [Education](#education) for services that require this type of order data.                                                           |
| **Employment records**                     | codt-employment                | Conditionally. See [Employment](#employment) for services that require this type of order data.                                                         |
| **Motor vehicle record (MVR)**             | codt-mvr                       | Conditionally. See [Motor vehicle record](#motor-vehicle-record) for services that require this type of order data.                                     |
| **Alternative names for a candidate**      | codt-alias                     | No. See [Aliases](#aliases) for services that support this type of order data.                                                                          |
| **Jurisdiction address**                   | codt-address                   | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data.                                                              |
| **County jurisdiction**                    | codt-jurisdiction-county       | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data.                                                              |
| **Federal district jurisdiction**          | codt-jurisdiction-fed-district | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data.                                                              |
| **State jurisdiction**                     | codt-jurisdiction-state        | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data.                                                              |
| **Professional license and certification** | codt-cplc                      | Conditionally. See [Professional license and certification](#professional-license-and-certification) for services that require this type of order data. |
| **Shipments**                              | codt-shipment                  | Conditionally. See [Shipments](#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](#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](#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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

```json theme={null}
{
  "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 |

```json theme={null}
{
  "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            |

```json theme={null}
{
  "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 |

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

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

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

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

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

**County jurisdictions:**

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

**Federal district jurisdictions:**

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

**State jurisdictions:**

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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:

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

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

```json theme={null}
{
  "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.           |

```json theme={null}
{
  "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.                              |

```json theme={null}
{
  "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.   |

```json theme={null}
{
  "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](/background-check-api/guides/document-processing-flow) for a full walkthrough of uploading documents and creating a document processing order.