Skip to main content
POST
/
api
/
v1
/
leads
const options = {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    phoneNumber: "6782319992",
    businessName: "Pacific Coast Container Haulers",
    assigneeType: "manual",
    checklistItems: [
      {
        code: "business_name",
        value: "Pacific Coast Container Haulers",
        status: "COMPLETED",
      },
      { code: "tax_id", value: "12-3456789", status: "COMPLETED" },
    ],
  }),
};

fetch("https://api-v2.getomni.ai/api/v1/leads", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "activitySummary": null,
    "assigneeType": "HUMAN_AGENT",
    "businessName": "Pacific Coast Container Haulers",
    "createdAt": "2026-01-30T02:00:00.000Z",
    "deletedAt": null,
    "didOptOut": false,
    "optOutAt": null,
    "email": "john@example.com",
    "emailVerifiedAt": "2026-01-30T02:00:00.000Z",
    "externalLeadId": null,
    "externalPortalLink": null,
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+16782319992",
    "phoneVerifiedAt": null,
    "source": "api",
    "tags": ["VIP", "priority-1"],
    "updatedAt": "2026-01-30T02:00:00.000Z",
    "website": null
  },
  "checklistItems": [
    {
      "id": "group-id",
      "name": "Business Information",
      "conditions": null,
      "items": [
        {
          "id": "lci-1",
          "checklistItemId": "ci-1",
          "value": "Pacific Coast Container Haulers",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-1",
            "code": "business_name",
            "label": "Business Name",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        },
        {
          "id": "lci-2",
          "checklistItemId": "ci-2",
          "value": "12-3456789",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-2",
            "code": "tax_id",
            "label": "Tax ID",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        }
      ]
    }
  ],
  "actionLogs": [],
  "matchingLeads": [],
  "lastAction": null,
  "nextFollowUp": null,
  "nextDraft": null
}

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 new lead. You can pass lead-level fields (firstName, lastName, email, etc.) and optional checklist item updates by code. A single API_ACTIVITY action log is written for “Lead created” with all updates grouped in the timeline.

​
Authentication

Requires the x-api-key header with a valid workspace API key.

​
Request Body

​
firstName
string
required
Lead first name
​
lastName
string
Lead last name
​
email
string
Lead email address
​
phoneNumber
string
Lead phone number (formatted or raw; stored in E.164 when possible)
​
middleName
string
Lead middle name
​
businessName
string
Business name
​
externalLeadId
string
External identifier for the lead (e.g. from a CRM system)
​
timezone
string
IANA timezone identifier (e.g. “America/New_York”). If not provided and a phone number is given, the timezone is inferred from the area code.
​
assigneeType
string
Who handles the lead: “agent” (AI) or “manual” (human)
​
didOptOut
boolean
When true, marks the lead as opted out and sets optOutAt to the current time.
​
emailVerified
boolean
When true, sets emailVerifiedAt to the current time (marks the lead’s email as verified).
​
checklistItems
array
Array of checklist updates. Each item: { "code": string, "value"?: any, "status"?: "TODO" | "COMPLETED" | "INVALID" | "SKIPPED" | "NEEDS_REVIEW" }. Use the checklist item code from your workspace.
​
tags
string[]
Set lead tags. Matching is case-insensitive, so “VIP” and “vip” are treated as the same tag. Tags are created automatically the first time a name is used. Pass [] to remove all tags.

​
Response

​
success
boolean
Whether the request succeeded
​
lead
object
The created lead record. Includes: id, activitySummary, assigneeType, businessName, createdAt, deletedAt, didOptOut, optOutAt, email, emailVerifiedAt, externalLeadId, externalPortalLink, firstName, lastName, phoneNumber, phoneVerifiedAt, source, tags, updatedAt, website.
​
checklistItems
array
Full checklist for the lead, grouped by checklist group. Each group includes id, name, conditions, and an items array. Each item includes id, checklistItemId, value, status, itemOverride, and a nested checklistItem with code, label, fieldType, conditions, validationRules, etc. File-type items include a documents array with presigned URLs.
​
actionLogs
array
Recent action logs for the lead (up to 100), enriched with tool info, messages, and document presigned URLs.
​
matchingLeads
array
Leads that share the same phone number or email (empty for test leads).
​
lastAction
object
The most recent completed outbound message or follow-up action log, including associated tool calls.
​
nextFollowUp
object
The next pending follow-up message action log, if any.
​
nextDraft
object
The next message awaiting approval, if any.
const options = {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    phoneNumber: "6782319992",
    businessName: "Pacific Coast Container Haulers",
    assigneeType: "manual",
    checklistItems: [
      {
        code: "business_name",
        value: "Pacific Coast Container Haulers",
        status: "COMPLETED",
      },
      { code: "tax_id", value: "12-3456789", status: "COMPLETED" },
    ],
  }),
};

fetch("https://api-v2.getomni.ai/api/v1/leads", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "activitySummary": null,
    "assigneeType": "HUMAN_AGENT",
    "businessName": "Pacific Coast Container Haulers",
    "createdAt": "2026-01-30T02:00:00.000Z",
    "deletedAt": null,
    "didOptOut": false,
    "optOutAt": null,
    "email": "john@example.com",
    "emailVerifiedAt": "2026-01-30T02:00:00.000Z",
    "externalLeadId": null,
    "externalPortalLink": null,
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+16782319992",
    "phoneVerifiedAt": null,
    "source": "api",
    "tags": ["VIP", "priority-1"],
    "updatedAt": "2026-01-30T02:00:00.000Z",
    "website": null
  },
  "checklistItems": [
    {
      "id": "group-id",
      "name": "Business Information",
      "conditions": null,
      "items": [
        {
          "id": "lci-1",
          "checklistItemId": "ci-1",
          "value": "Pacific Coast Container Haulers",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-1",
            "code": "business_name",
            "label": "Business Name",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        },
        {
          "id": "lci-2",
          "checklistItemId": "ci-2",
          "value": "12-3456789",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-2",
            "code": "tax_id",
            "label": "Tax ID",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        }
      ]
    }
  ],
  "actionLogs": [],
  "matchingLeads": [],
  "lastAction": null,
  "nextFollowUp": null,
  "nextDraft": null
}