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

# Update Lead

`PATCH /api/leads`

## Request

- Base URL: `https://octanist.com`
- URL: `https://octanist.com/api/leads`
- Auth: API key in header `X-API-KEY`

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.dev/octanist/apis/octanist-api.md) - [All operations](https://skmtc.dev/octanist/apis/octanist-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octanist/apis/octanist-api/revisions/29a41aff4975?raw)
