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"
}
}
Leads
Create Lead Checklist Item
Add a one-off checklist requirement to a single lead
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));
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 thex-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.
Response
boolean
Whether the request succeeded
object
The created lead checklist item.
Show checklistItem
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 itemsobject
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"
}
}