Skip to main content
PUT
/
api
/
v1
/
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));

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

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

​
leadId
string
required
Omni lead ID of the lead to update.
​
firstName
string
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. When false, clears the opt-out status.
​
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.
​
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. Only the items you include will be updated.
​
tags
string[]
Set lead tags. Matching is case-insensitive, so “VIP” and “vip” are treated as the same tag. Pass [] to remove all tags.

​
Response

​
success
boolean
Whether the request succeeded
​
status
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.
​
lead
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.
​
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.
// 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));

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