Skip to main content
POST
/
api
/
v1
/
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));

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

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.

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: "DATE", "EIN", "EMAIL", "NUMBER", "PHONE", "SELECT", "TEXT"
​
config
object
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 }
​
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.
[
  "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.

​
Response

​
success
boolean
Whether the request succeeded
​
checklistItem
object
The created 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));

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