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

# Batch Create Lead Checklist Items

> Add multiple one-off checklist requirements to a single lead

This endpoint adds several custom checklist requirements to a specific lead. It
behaves like [Create Lead Checklist Item](/api-reference/leads/create-lead-checklist-item),
but accepts an array of items.

Each item is processed independently and the response reports a per-item result,
so a problem with one item does not stop the others from being created. Items
created this way are scoped to the lead — they do not affect your template
checklists or any other lead.

## Authentication

Requires the `x-api-key` header with a valid workspace API key.

## Path Parameters

<ParamField path="leadId" type="string" required>
  Unique identifier of the lead to add the checklist items to.
</ParamField>

## Request Body

<ParamField body="items" type="object[]" required>
  Array of checklist items to create. Must contain between 1 and 25 items.
  Each item has the same shape as the body of
  [Create Lead Checklist Item](/api-reference/leads/create-lead-checklist-item):

  <Expandable title="item">
    <ParamField body="label" type="string" required>
      Label shown in the dashboard and portal. Example: `"Utility bill"`.
    </ParamField>

    <ParamField body="fieldType" type="enum" required>
      Type of data being collected. Determines the expected `config` shape.

      * **Files**: `"BANK_STATEMENT"`, `"FILE"`, `"ID"`, `"TAX_RETURN"`
      * **Fields**: `"ADDRESS"`, `"DATE"`, `"EIN"`, `"EMAIL"`, `"MULTI_SELECT"`, `"NUMBER"`, `"PHONE"`, `"SELECT"`, `"SSN"`, `"TEXT"`
    </ParamField>

    <ParamField body="config" type="object" required={false}>
      Type-specific configuration.

      * `BANK_STATEMENT`: `{ months: number, gracePeriodDays?: number, isPersonal?: boolean }`
      * `ID`: `{ type: "DRIVERS_LICENSE" | "PASSPORT" }`
      * `MULTI_SELECT`: `{ options: string[] }`
      * `NUMBER`: `{ min?: number, max?: number }`
      * `SELECT`: `{ options: string[] }`
      * `TAX_RETURN`: `{ years: number, isPersonal?: boolean }`
      * `TEXT`: `{ pattern?: string }`
    </ParamField>

    <ParamField body="isRequired" type="boolean" required={false}>
      Whether the lead must complete this item. Defaults to `true`.
    </ParamField>

    <ParamField body="agentInstructions" type="string" required={false}>
      Instructions for the AI agent. Use this to guide how the agent should
      interpret, request, or evaluate this field.
    </ParamField>

    <ParamField body="clientInstructions" type="string" required={false}>
      Instructions shown to the lead in the portal.
    </ParamField>

    <ParamField body="validationRules" type="string[]" required={false}>
      Applies only to file-type fields. Natural-language rules the AI
      validator checks against uploaded documents.
    </ParamField>

    <ParamField body="code" type="string" required={false}>
      Stable identifier for the checklist item. If omitted, one is generated
      from the label. Provide your own if you need to reference this item from
      an external system. Must be unique per lead.
    </ParamField>
  </Expandable>
</ParamField>

## Response

The endpoint returns `201` with a `results` array in the same order as the
submitted `items`. Each entry reports whether that item was created — inspect
each entry's `success` field to see which ones succeeded.

<ResponseField name="results" type="object[]">
  Per-item outcomes, in the same order as the request `items`.

  <Expandable title="result">
    <ResponseField name="success" type="boolean">
      Whether this item was created.
    </ResponseField>

    <ResponseField name="checklistItem" type="object">
      The created lead checklist item. Present only when `success` is `true`.
      Same shape as the response of
      [Create Lead Checklist Item](/api-reference/leads/create-lead-checklist-item).
    </ResponseField>

    <ResponseField name="error" type="string">
      Reason the item could not be created. Present only when `success` is
      `false` (for example, a duplicate `code`).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```javascript Node.js theme={null}
  const leadId = "4ef30123-90c2-4dc0-bd28-b43eee8664ea";
  const options = {
    method: "POST",
    headers: {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      items: [
        {
          label: "Utility bill",
          fieldType: "FILE",
          clientInstructions: "Please upload a recent utility bill",
        },
        {
          label: "Annual revenue",
          fieldType: "NUMBER",
          config: { min: 0 },
        },
      ],
    }),
  };

  fetch(
    `https://api-v2.getomni.ai/api/v1/leads/${leadId}/checklist-items/batch`,
    options,
  )
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
  ```

  ```python Python theme={null}
  import requests

  lead_id = "4ef30123-90c2-4dc0-bd28-b43eee8664ea"
  url = f"https://api-v2.getomni.ai/api/v1/leads/{lead_id}/checklist-items/batch"
  headers = {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
  }
  payload = {
      "items": [
          {
              "label": "Utility bill",
              "fieldType": "FILE",
              "clientInstructions": "Please upload a recent utility bill",
          },
          {
              "label": "Annual revenue",
              "fieldType": "NUMBER",
              "config": {"min": 0},
          },
      ]
  }

  response = requests.request("POST", url, headers=headers, json=payload)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api-v2.getomni.ai/api/v1/leads/4ef30123-90c2-4dc0-bd28-b43eee8664ea/checklist-items/batch \
    --header 'x-api-key: <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "items": [
        {
          "label": "Utility bill",
          "fieldType": "FILE",
          "clientInstructions": "Please upload a recent utility bill"
        },
        {
          "label": "Annual revenue",
          "fieldType": "NUMBER",
          "config": { "min": 0 }
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "results": [
      {
        "success": true,
        "checklistItem": {
          "id": "9f1c4d80-4a2b-4f0e-8c2c-93a0a9c9b2a1",
          "leadId": "4ef30123-90c2-4dc0-bd28-b43eee8664ea",
          "code": "UTILITY_BILL",
          "label": "Utility bill",
          "fieldType": "FILE",
          "isRequired": true,
          "status": "TODO",
          "agentInstructions": null,
          "clientInstructions": "Please upload a recent utility bill",
          "createdAt": "2026-05-04T18:21:30.123Z"
        }
      },
      {
        "success": false,
        "error": "Checklist item with code \"ANNUAL_REVENUE\" already exists for this lead"
      }
    ]
  }
  ```
</ResponseExample>