Update Lead

// Update lead fields and checklist items
const options = {
  method: "PUT",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    leadId: "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    lastName: "Francisco",
    businessName: "OmniAI Technology LLC",
    checklistItems: [
      {
        code: "legal_name",
        value: "OmniAI Technology LLC",
        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 = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
        {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"},
    ],
}

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

curl --request PUT \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
      {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"}
    ]
  }'

{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "activitySummary": null,
    "assigneeType": "HUMAN_AGENT",
    "businessName": "OmniAI Technology LLC",
    "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": "Francisco",
    "phoneNumber": "+16782319992",
    "phoneVerifiedAt": null,
    "source": "api",
    "tags": ["VIP", "priority-1"],
    "updatedAt": "2026-01-30T02:05: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-3",
          "checklistItemId": "ci-3",
          "value": "OmniAI Technology LLC",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-3",
            "code": "legal_name",
            "label": "Legal Name",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        }
      ]
    }
  ],
  "actionLogs": [
    {
      "id": "log-1",
      "type": "API_ACTIVITY",
      "status": "COMPLETED",
      "summary": "Lead updated",
      "input": {
        "eventType": "lead_updated",
        "source": "api",
        "leadUpdates": {
          "lastName": "Francisco",
          "businessName": "OmniAI Technology LLC"
        },
        "checklistUpdates": [
          {
            "code": "legal_name",
            "value": "OmniAI Technology LLC",
            "status": "COMPLETED",
            "success": true
          }
        ]
      },
      "createdAt": "2026-01-30T02:05:00.000Z"
    }
  ],
  "matchingLeads": [],
  "lastAction": null,
  "nextFollowUp": null,
  "nextDraft": null
}

PUT

api

leads

// Update lead fields and checklist items
const options = {
  method: "PUT",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    leadId: "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    lastName: "Francisco",
    businessName: "OmniAI Technology LLC",
    checklistItems: [
      {
        code: "legal_name",
        value: "OmniAI Technology LLC",
        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 = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
        {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"},
    ],
}

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

curl --request PUT \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
      {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"}
    ]
  }'

{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "activitySummary": null,
    "assigneeType": "HUMAN_AGENT",
    "businessName": "OmniAI Technology LLC",
    "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": "Francisco",
    "phoneNumber": "+16782319992",
    "phoneVerifiedAt": null,
    "source": "api",
    "tags": ["VIP", "priority-1"],
    "updatedAt": "2026-01-30T02:05: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-3",
          "checklistItemId": "ci-3",
          "value": "OmniAI Technology LLC",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-3",
            "code": "legal_name",
            "label": "Legal Name",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        }
      ]
    }
  ],
  "actionLogs": [
    {
      "id": "log-1",
      "type": "API_ACTIVITY",
      "status": "COMPLETED",
      "summary": "Lead updated",
      "input": {
        "eventType": "lead_updated",
        "source": "api",
        "leadUpdates": {
          "lastName": "Francisco",
          "businessName": "OmniAI Technology LLC"
        },
        "checklistUpdates": [
          {
            "code": "legal_name",
            "value": "OmniAI Technology LLC",
            "status": "COMPLETED",
            "success": true
          }
        ]
      },
      "createdAt": "2026-01-30T02:05:00.000Z"
    }
  ],
  "matchingLeads": [],
  "lastAction": null,
  "nextFollowUp": null,
  "nextDraft": null
}

This endpoint updates an existing lead. Only the fields you include in the request body will be changed; omitted fields are left untouched. You can update lead-level fields (firstName, lastName, email, etc.) and/or checklist items by code. A single API_ACTIVITY action log is written for “Lead updated” with all updates grouped in the timeline.

Authentication

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

Request Body

string

required

Omni lead ID of the lead to update.

string

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. When false, clears the opt-out status.

string

Set the lead’s status. Allowed values are "COMPLETED", "IN_PROGRESS", "NOT_INTERESTED", and "OPTED_OUT" (note that "REVIEW" is not settable via the API). If didOptOut is also provided, it must agree with status. When set to "COMPLETED", any still-incomplete required checklist items are auto-skipped. When set to "NOT_INTERESTED", the lead is marked as not interested and future follow-ups stop. When set to "OPTED_OUT", the lead is opted out and in-flight outbound messages are cancelled. When set to "IN_PROGRESS", auto-skips from a prior "COMPLETED" transition are cleared and the lead is re-opened.

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. Only the items you include will be updated.

string[]

Set lead tags. Matching is case-insensitive, so “VIP” and “vip” are treated as the same tag. Pass [] to remove all tags.

Response

boolean

Whether the request succeeded

string

The lead’s current status after the update. One of "COMPLETED", "IN_PROGRESS", "NOT_INTERESTED", "OPTED_OUT", or "REVIEW". "REVIEW" is not settable via this endpoint but may appear in the response when the lead has an unresolved escalation.

object

The updated lead record. Includes: id, activitySummary, assigneeType, businessName, createdAt, deletedAt, didOptOut, optOutAt, notInterestedAt, 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.

// Update lead fields and checklist items
const options = {
  method: "PUT",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    leadId: "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    lastName: "Francisco",
    businessName: "OmniAI Technology LLC",
    checklistItems: [
      {
        code: "legal_name",
        value: "OmniAI Technology LLC",
        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 = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
        {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"},
    ],
}

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

curl --request PUT \
  --url https://api-v2.getomni.ai/api/v1/leads \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "lastName": "Francisco",
    "businessName": "OmniAI Technology LLC",
    "checklistItems": [
      {"code": "legal_name", "value": "OmniAI Technology LLC", "status": "COMPLETED"}
    ]
  }'

{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "activitySummary": null,
    "assigneeType": "HUMAN_AGENT",
    "businessName": "OmniAI Technology LLC",
    "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": "Francisco",
    "phoneNumber": "+16782319992",
    "phoneVerifiedAt": null,
    "source": "api",
    "tags": ["VIP", "priority-1"],
    "updatedAt": "2026-01-30T02:05: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-3",
          "checklistItemId": "ci-3",
          "value": "OmniAI Technology LLC",
          "status": "COMPLETED",
          "itemOverride": null,
          "checklistItem": {
            "id": "ci-3",
            "code": "legal_name",
            "label": "Legal Name",
            "fieldType": "TEXT",
            "isRequired": true,
            "conditions": null
          }
        }
      ]
    }
  ],
  "actionLogs": [
    {
      "id": "log-1",
      "type": "API_ACTIVITY",
      "status": "COMPLETED",
      "summary": "Lead updated",
      "input": {
        "eventType": "lead_updated",
        "source": "api",
        "leadUpdates": {
          "lastName": "Francisco",
          "businessName": "OmniAI Technology LLC"
        },
        "checklistUpdates": [
          {
            "code": "legal_name",
            "value": "OmniAI Technology LLC",
            "status": "COMPLETED",
            "success": true
          }
        ]
      },
      "createdAt": "2026-01-30T02:05:00.000Z"
    }
  ],
  "matchingLeads": [],
  "lastAction": null,
  "nextFollowUp": null,
  "nextDraft": null
}

Batch Create Lead Checklist Items Get Document

Getting Started

Leads

Documents

Spreads

Artifacts

Analytics

Webhooks

Authentication

Request Body

Response

​Authentication

​Request Body

​Response

Authentication

Request Body

Response