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

# 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

**leadId** `string` *required*

Monumint 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

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

```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: "Monumint Technology LLC",
    checklistItems: [
      {
        code: "legal_name",
        value: "Monumint 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": "Monumint Technology LLC",
    "checklistItems": [
        {"code": "legal_name", "value": "Monumint 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": "Monumint Technology LLC",
    "checklistItems": [
      {"code": "legal_name", "value": "Monumint Technology LLC", "status": "COMPLETED"}
    ]
  }'
```

```json 200 theme={null}
{
  "success": true,
  "lead": {
    "id": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    "assigneeType": "HUMAN_AGENT",
    "businessName": "Monumint 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": "Monumint 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": "Monumint Technology LLC"
        },
        "checklistUpdates": [
          {
            "code": "legal_name",
            "value": "Monumint Technology LLC",
            "status": "COMPLETED",
            "success": true
          }
        ]
      },
      "createdAt": "2026-01-30T02:05:00.000Z"
    }
  ],
  "matchingLeads": []
}
```


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