Create Lead Checklist Item

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));

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())

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

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

POST

api

leads

{leadId}

checklist-items

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));

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())

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

{
  "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 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

string

required

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

Request Body

string

required

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

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"

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 }

boolean

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

string

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

string

Instructions shown to the lead in the portal.

string[]

Applies only to file-type fields. Natural-language rules the AI validator checks against uploaded documents.

[
  "Document is dated within the last 90 days",
  "Account holder name matches the lead's name on the application"
]

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.

string

Beta The workflow run to add the item to. Get it from the id of a run returned by List Workflow Runs or from any workflow_run.* webhook.

Response

boolean

Whether the request succeeded

object

The created lead checklist item.

Show checklistItem

string

Unique identifier for this checklist item

string

Lead this requirement belongs to

string

Stable identifier (auto-generated if not supplied)

string

Label

enum

Field type as provided in the request

boolean

Whether the lead must complete this item

enum

Initial status — always "TODO" for new items

object

Type-specific configuration as provided in the request

string

Agent-facing instructions

string

Client-facing instructions

string

ISO 8601 timestamp

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));

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())

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

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

Getting Started

Leads

Workflow Runs

Agents

Workflows

Documents

Analytics

Webhooks

Create Lead Checklist Item

Authentication

Path Parameters

Request Body

Response

​Authentication

​Path Parameters

​Request Body

​Response

Authentication

Path Parameters

Request Body

Response