> ## 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.

# Create Lead

> Create a new lead with optional checklist item updates

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

<ParamField path="firstName" type="string" required>
  Lead first name
</ParamField>

<ParamField path="lastName" type="string" required={false}>
  Lead last name
</ParamField>

<ParamField path="email" type="string" required={false}>
  Lead email address
</ParamField>

<ParamField path="phoneNumber" type="string" required={false}>
  Lead phone number (formatted or raw; stored in E.164 when possible)
</ParamField>

<ParamField path="middleName" type="string" required={false}>
  Lead middle name
</ParamField>

<ParamField path="businessName" type="string" required={false}>
  Business name
</ParamField>

<ParamField path="externalLeadId" type="string" required={false}>
  External identifier for the lead (e.g. from a CRM system)
</ParamField>

<ParamField path="timezone" type="string" required={false}>
  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.
</ParamField>

<ParamField path="assigneeType" type="string" required={false}>
  Who handles the lead: "agent" (AI) or "manual" (human)
</ParamField>

<ParamField path="didOptOut" type="boolean" required={false}>
  When true, marks the lead as opted out and sets optOutAt to the current time.
</ParamField>

<ParamField path="emailVerified" type="boolean" required={false}>
  When true, sets emailVerifiedAt to the current time (marks the lead's email as
  verified).
</ParamField>

<ParamField path="checklistItems" type="array" required={false}>
  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.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="lead" type="object">
  The created lead record. Includes: id, activitySummary, assigneeType,
  businessName, createdAt, deletedAt, didOptOut, optOutAt, email,
  emailVerifiedAt, externalLeadId, externalPortalLink, firstName, lastName,
  phoneNumber, phoneVerifiedAt, source, updatedAt, website.
</ResponseField>

<ResponseField name="checklistItems" type="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.
</ResponseField>

<ResponseField name="actionLogs" type="array">
  Recent action logs for the lead (up to 100), enriched with tool info,
  messages, and document presigned URLs.
</ResponseField>

<ResponseField name="matchingLeads" type="array">
  Leads that share the same phone number or email (empty for test leads).
</ResponseField>

<ResponseField name="lastAction" type="object" nullable>
  The most recent completed outbound message or follow-up action log, including
  associated tool calls.
</ResponseField>

<ResponseField name="nextFollowUp" type="object" nullable>
  The next pending follow-up message action log, if any.
</ResponseField>

<ResponseField name="nextDraft" type="object" nullable>
  The next message awaiting approval, if any.
</ResponseField>

<RequestExample>
  ```javascript Node.js theme={null}
  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));
  ```

  ```python Python theme={null}
  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())
  ```

  ```bash cURL theme={null}
  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"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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",
      "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
  }
  ```
</ResponseExample>