Create Lead

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

import requests

url = "https://api-v2.getomni.ai/api/v1/leads"
headers = {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
}
payload = {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": True,
    "checklistItems": [
        {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
        {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"},
    ],
}

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

curl --request POST \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": true,
    "checklistItems": [
      {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
      {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"}
    ]
  }'

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

POST

api

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

import requests

url = "https://api-v2.getomni.ai/api/v1/leads"
headers = {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
}
payload = {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": True,
    "checklistItems": [
        {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
        {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"},
    ],
}

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

curl --request POST \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": true,
    "checklistItems": [
      {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
      {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"}
    ]
  }'

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

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

string

required

Lead first name

string

Lead last name

string

Lead email address

string

Lead phone number (formatted or raw; stored in E.164 when possible)

string

Lead middle name

string

Business name

string

Business or lead website URL

string

External identifier for the lead (e.g. from a CRM system)

string

URL of the lead’s external portal, used instead of the default portal URL

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.

string

Who handles the lead: “agent” (AI) or “manual” (human)

boolean

When true, marks the lead as opted out and sets optOutAt to the current time.

boolean

When true, sets emailVerifiedAt to the current time (marks the lead’s email as verified).

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.

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

boolean

Whether the request succeeded

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.

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.

array

Recent action logs for the lead (up to 100), enriched with tool info, messages, and document presigned URLs.

array

Leads that share the same phone number or email (empty for test leads).

object

The most recent completed outbound message or follow-up action log, including associated tool calls.

object

The next pending follow-up message action log, if any.

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

import requests

url = "https://api-v2.getomni.ai/api/v1/leads"
headers = {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
}
payload = {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": True,
    "checklistItems": [
        {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
        {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"},
    ],
}

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

curl --request POST \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "6782319992",
    "businessName": "Pacific Coast Container Haulers",
    "assigneeType": "manual",
    "emailVerified": true,
    "checklistItems": [
      {"code": "business_name", "value": "Pacific Coast Container Haulers", "status": "COMPLETED"},
      {"code": "tax_id", "value": "12-3456789", "status": "COMPLETED"}
    ]
  }'

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

Trigger Follow-up Create Lead Checklist Item

Getting Started

Leads

Documents

Spreads

Artifacts

Analytics

Webhooks

Authentication

Request Body

Response

​Authentication

​Request Body

​Response

Authentication

Request Body

Response