---
title: "Update Lead"
method: PATCH
path: "/api/leads"
tags: ["Leads"]
---

# Update Lead

`PATCH /api/leads`

Update an existing lead. Matches leads by `id`, `externalId`, `email`, or `phone` (in that priority order). At least one identifier is required. `email` and `phone` can be strings or arrays of up to 10 strings. Array values are tried sequentially. The external ID is used for lookup and is not changed by this endpoint.

## Request body

- UpdateLeadRequest — At least one of id, externalId, email, or phone is required as an identifier. `email` and `phone` can be strings or arrays of up to 10 strings. Identifiers are tried sequentially: id first, then externalId, then email values in order, then phone values in order. externalId is used for lookup and is not changed by this endpoint.
  - `id` string — Lead ID (highest priority match)
  - `externalId` string — Customer-owned lead identifier (second priority match). Whitespace is trimmed.
  - `email` union — Lead email or ordered email candidates (third priority match). Arrays are tried sequentially.
    - string, email
    - string[]
  - `phone` union — Lead phone or ordered phone candidates (fourth priority match). Arrays are tried sequentially after all email candidates.
    - string
    - string[]
  - `status` 'qualified' | 'won' | 'lost' — New status. Takes precedence over `changedTo` if both are provided.
  - `changedTo` 'qualified' | 'won' | 'lost' — Legacy alias for `status` (same values).
  - `value` union — Lead value. Strings are auto-converted to numbers.
    - number
    - string
  - `note` string — Note to attach to the lead
  - `lossReason` string — Reason for loss (only used when status is `lost`)

## Response `200`

Lead updated successfully

- object
  - `success` boolean
  - `data` object
    - `leadId` string
    - `externalId` string, nullable
    - `leadsUpdated` integer
    - `message` string
  - `meta` Meta
    - `requestId` string
    - `timestamp` string, date-time

## Other responses

- `400` — Invalid JSON or missing identifier
- `401` — Missing or invalid API key
- `404` — No lead found matching the provided identifiers
- `409` — Multiple leads match; provide a more specific identifier
- `500` — Server error

---

[API](https://skmtc.net/octanist/apis/octanist-api.md) · [All operations](https://skmtc.net/octanist/apis/octanist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octanist/octanist-api/revisions/a0620637a051/schema)