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

# Update Lead

> Update an existing lead with optional checklist item updates

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

<ParamField body="leadId" type="string" required>
  Omni lead ID of the lead to update.
</ParamField>

<ParamField body="firstName" type="string" required={false}>
  Lead first name
</ParamField>

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

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

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

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

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

<ParamField body="website" type="string" required={false}>
  Business or lead website URL
</ParamField>

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

<ParamField body="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 body="assigneeType" type="string" required={false}>
  Who handles the lead: "agent" (AI) or "manual" (human)
</ParamField>

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

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

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

<ParamField body="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. Only the items you include will be updated.
</ParamField>

<ParamField body="tags" type="string[]" required={false}>
  Set lead tags. Matching is case-insensitive, so "VIP" and "vip" are treated as
  the same tag. Pass \[] to remove all tags.
</ParamField>

## Response

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

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

<ResponseField name="lead" type="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.
</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}
  // 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));
  ```

  ```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 = {
      "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())
  ```

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

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