> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monumint.com/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

**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

**website** `string`

Business or lead website URL

**externalLeadId** `string`

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

**externalPortalUrl** `string`

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

**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. If the same code is used in more than one checklist group, prefix it with the group's code, e.g. `CONTACT_INFO.EMAIL_ADDRESS`.

**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, 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).

```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"}
    ]
  }'
```

```json 201 theme={null}
{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "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": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.