> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monumint.com/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

**leadId** `string` *required*

Unique identifier of the lead to add the checklist item to.

## Request Body

**label** `string` *required*

Label shown in the dashboard and portal. Example: `"Utility bill"`.

**fieldType** `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"`

**config** `object`

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 }`

**isRequired** `boolean`

Whether the lead must complete this item. Defaults to `true`.

**agentInstructions** `string`

Instructions for the AI agent. Use this to guide how the agent should
interpret, request, or evaluate this field.

**clientInstructions** `string`

Instructions shown to the lead in the portal.

**validationRules** `string[]`

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"
]
```

**code** `string`

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.

**workflowRunId** `string`

Beta The workflow run to add the item to. Get it from the `id`
of a run returned by
[List Workflow Runs](https://docs.monumint.com/api-reference/workflow-runs/list-workflow-runs.md) or from
any `workflow_run.*` webhook.

## Response

**success** `boolean`

Whether the request succeeded

**checklistItem** `object`

The created lead checklist item.

**checklistItem**

**id** `string`

Unique identifier for this checklist item

**leadId** `string`

Lead this requirement belongs to

**code** `string`

Stable identifier (auto-generated if not supplied)

**label** `string`

Label

**fieldType** `enum`

Field type as provided in the request

**isRequired** `boolean`

Whether the lead must complete this item

**status** `enum`

Initial status — always `"TODO"` for new items

**config** `object`

Type-specific configuration as provided in the request

**agentInstructions** `string`

Agent-facing instructions

**clientInstructions** `string`

Client-facing instructions

**createdAt** `string`

ISO 8601 timestamp

```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"
  }'
```

```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"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.