> ## 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.

# Create Lead Checklist Item

> Add a one-off checklist requirement to a single lead

This endpoint creates a custom checklist requirement on a specific lead. Use it
when a lead needs a piece of information or document that isn't part of your
agent's standard checklist (e.g. an extra utility bill, a one-off attestation,
or a loan-specific tax document). The item appears on the lead's checklist
immediately and can be completed via the portal, the dashboard, or the API.

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 item to.
</ParamField>

## Request Body

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

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

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

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

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

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

<ParamField path="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 path="clientInstructions" type="string" required={false}>
  Instructions shown to the lead in the portal.
</ParamField>

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

  ```json theme={null}
  [
    "Document is dated within the last 90 days",
    "Account holder name matches the lead's name on the application"
  ]
  ```
</ParamField>

<ParamField path="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.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="checklistItem" type="object">
  The created lead checklist item.

  <Expandable title="checklistItem">
    <ResponseField name="id" type="string">
      Unique identifier for this checklist item
    </ResponseField>

    <ResponseField name="leadId" type="string">
      Lead this requirement belongs to
    </ResponseField>

    <ResponseField name="code" type="string">
      Stable identifier (auto-generated if not supplied)
    </ResponseField>

    <ResponseField name="label" type="string">
      Label
    </ResponseField>

    <ResponseField name="fieldType" type="enum">
      Field type as provided in the request
    </ResponseField>

    <ResponseField name="isRequired" type="boolean">
      Whether the lead must complete this item
    </ResponseField>

    <ResponseField name="status" type="enum">
      Initial status — always `"TODO"` for new items
    </ResponseField>

    <ResponseField name="config" type="object" nullable>
      Type-specific configuration as provided in the request
    </ResponseField>

    <ResponseField name="agentInstructions" type="string" nullable>
      Agent-facing instructions
    </ResponseField>

    <ResponseField name="clientInstructions" type="string" nullable>
      Client-facing instructions
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </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({
      label: "Utility bill",
      fieldType: "FILE",
      isRequired: true,
      agentInstructions: "From the last 90 days",
      clientInstructions: "Please upload a PDF or photo of a recent utility bill",
    }),
  };

  fetch(
    `https://api-v2.getomni.ai/api/v1/leads/${leadId}/checklist-items`,
    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"
  headers = {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
  }
  payload = {
      "label": "Utility bill",
      "fieldType": "FILE",
      "isRequired": True,
      "agentInstructions": "From the last 90 days",
      "clientInstructions": "Please upload a PDF or photo of a recent utility bill",
  }

  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 \
    --header 'x-api-key: <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "label": "Utility bill",
      "fieldType": "FILE",
      "isRequired": true,
      "agentInstructions": "From the last 90 days",
      "clientInstructions": "Please upload a PDF or photo of a recent utility bill"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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": "From the last 90 days",
      "clientInstructions": "Please upload a PDF or photo of a recent utility bill",
      "createdAt": "2026-05-04T18:21:30.123Z"
    }
  }
  ```
</ResponseExample>