> ## Documentation Index > Fetch the complete documentation index at: https://octanist.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Lead > Update an existing lead Update an existing lead. Matches leads by `id`, `externalId`, `email`, or `phone` (in that priority order). At least one identifier (`id`, `externalId`, `email`, or `phone`) is required. `email` and `phone` can be sent as a single string or as an array of up to 10 strings. Array values are tried sequentially. Octanist first tries the first email, then the next email, and only moves on to phone values if none of the email values match. ## Request Body | Field | Type | Required | Description | | ------------ | ------------------- | -------- | -------------------------------------------------------------------------- | | `id` | string | No\* | Lead ID (highest priority match) | | `externalId` | string | No\* | Customer-owned lead identifier (second priority match, max 255 characters) | | `email` | string \| string\[] | No\* | Lead email or ordered email candidates (third priority match, max 10) | | `phone` | string \| string\[] | No\* | Lead phone or ordered phone candidates (fourth priority match, max 10) | | `status` | string | No | New status: `qualified`, `won`, or `lost` | | `changedTo` | string | No | Legacy alias for `status` (same values) | | `value` | number \| string | No | Lead value (strings are auto-converted to numbers) | | `note` | string | No | Note to attach to the lead | | `lossReason` | string | No | Reason for loss (only used when `status` is `lost`) | \* At least one of `id`, `externalId`, `email`, or `phone` is required. When both `status` and `changedTo` are provided, `status` takes precedence. When `email` or `phone` is an array, values are matched in order and the first value with a match wins. The matching order is: 1. `id`, if provided 2. `externalId`, if provided 3. `email[0]`, `email[1]`, and so on 4. `phone[0]`, `phone[1]`, and so on When matching by `email` or `phone`, multiple leads may match. If your organization settings allow bulk updates, all matching leads are updated. Otherwise, a `409 CONFLICT` error is returned. `externalId` is a lookup identifier on this endpoint. It does not replace or rotate the external ID stored on the lead. ## Example Request ```bash theme={null} curl -X PATCH \ -H "X-API-KEY: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "john@example.com", "status": "won", "value": 5000 }' \ "https://octanist.com/api/leads" ``` ## Example Request With Fallback Identifiers ```bash theme={null} curl -X PATCH \ -H "X-API-KEY: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": ["primary@example.com", "billing@example.com"], "phone": ["+31612345678", "+31687654321"], "status": "qualified" }' \ "https://octanist.com/api/leads" ``` ## Example Request by External ID ```bash theme={null} curl -X PATCH \ -H "X-API-KEY: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "externalId": "QUOTE-2026-0042", "status": "won", "value": 5000 }' \ "https://octanist.com/api/leads" ``` ## Example Response ```json theme={null} { "success": true, "data": { "leadId": "lead_abc123", "externalId": "QUOTE-2026-0042", "leadsUpdated": 1, "message": "Lead updated successfully" }, "meta": { "requestId": "req_a1b2c3d4e5f6", "timestamp": "2026-03-10T12:00:00.000Z" } } ``` ## Error Responses | Status | Code | Description | | ------ | ------------------ | -------------------------------------------------------- | | 400 | `VALIDATION_ERROR` | Invalid JSON or missing identifier | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 404 | `NOT_FOUND` | No lead found matching the provided identifiers | | 409 | `CONFLICT` | Multiple leads match; provide a more specific identifier | | 500 | `INTERNAL_ERROR` | Server error | ## OpenAPI ````yaml PATCH /api/leads openapi: 3.0.1 info: title: Octanist API description: >- The Octanist API allows you to manage leads, retrieve statistics, and access ad spend data. version: 2.2.0 contact: name: Octanist Support url: https://octanist.com/docs servers: - url: https://octanist.com description: Production server security: - apiKeyAuth: [] paths: /api/leads: patch: tags: - Leads summary: Update Lead description: >- 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. requestBody: description: >- Lead update data. At least one of id, externalId, email, or phone is required. required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLeadRequest' responses: '200': description: Lead updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: leadId: type: string example: lead_abc123 externalId: type: string nullable: true example: QUOTE-2026-0042 leadsUpdated: type: integer example: 1 message: type: string example: Lead updated successfully meta: $ref: '#/components/schemas/Meta' '400': description: Invalid JSON or missing identifier content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No lead found matching the provided identifiers content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Multiple leads match; provide a more specific identifier content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: UpdateLeadRequest: type: object description: >- 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. properties: id: type: string description: Lead ID (highest priority match) example: lead_abc123 externalId: type: string minLength: 1 maxLength: 255 description: >- Customer-owned lead identifier (second priority match). Whitespace is trimmed. example: QUOTE-2026-0042 email: oneOf: - type: string format: email - type: array items: type: string format: email minItems: 1 maxItems: 10 description: >- Lead email or ordered email candidates (third priority match). Arrays are tried sequentially. example: john@example.com phone: oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 10 description: >- Lead phone or ordered phone candidates (fourth priority match). Arrays are tried sequentially after all email candidates. example: '+1234567890' status: type: string enum: - qualified - won - lost description: New status. Takes precedence over `changedTo` if both are provided. example: won changedTo: type: string enum: - qualified - won - lost description: Legacy alias for `status` (same values). example: won value: oneOf: - type: number - type: string description: Lead value. Strings are auto-converted to numbers. example: 5000 note: type: string description: Note to attach to the lead lossReason: type: string description: Reason for loss (only used when status is `lost`) Meta: type: object properties: requestId: type: string example: req_a1b2c3d4e5f6 timestamp: type: string format: date-time example: '2026-03-10T12:00:00.000Z' ErrorResponse: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string description: Error code example: VALIDATION_ERROR message: type: string description: Human readable error message example: Human readable error message details: type: object description: Optional additional error details meta: $ref: '#/components/schemas/Meta' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication ````