> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uservox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Lead

> Update a lead's metadata and optionally transition to a new state

## Overview

<Note>
  **Asynchronous Endpoint**: This endpoint queues the lead update for background processing and responds immediately. The actual outcome of the update will be sent via webhook callbacks configured in your Process.
</Note>

## Body Parameters

<ParamField body="leadId" type="string">
  MongoDB ObjectId of the lead (required if not using referenceId)
</ParamField>

<ParamField body="referenceId" type="string">
  External reference ID (requires projectId and processId)
</ParamField>

<ParamField body="projectId" type="string">
  Required when using referenceId
</ParamField>

<ParamField body="processId" type="string">
  Required when using referenceId
</ParamField>

<ParamField body="metadata" type="object">
  Metadata object to merge with existing metadata
</ParamField>

<ParamField body="name" type="string">
  Update the lead's name
</ParamField>

<ParamField body="targetState" type="string">
  Target state to transition the lead to (e.g., "interested", "lost", "followup\_2")
</ParamField>

<ParamField body="disposition" type="string">
  Disposition reason (used with targetState "interested" or "lost")
</ParamField>

<ParamField body="userId" type="string">
  User ID for audit logging
</ParamField>

<Note>
  If `metadata` is not provided, all other fields (except leadId, referenceId, projectId, processId, targetState, name, disposition, userId) will be merged into metadata.
</Note>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the update request was successfully accepted
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message (e.g., "Lead update initiated")
</ResponseField>

## Webhook Notifications

Once the asynchronous update job finishes processing, a webhook will be sent to the callback URLs configured in the Lead's Process.

<Tabs>
  <Tab title="Success Payload">
    This payload is sent when the lead is successfully updated and transitioned (if requested).

    ```json theme={null}
    {
      "action_type": "update",
      "updateId": "65e4b2d9f1a2...",
      "success": true,
      "error": null,
      "leadId": "696102a4b8...",
      "referenceId": "AB123456789",
      "timestamp": 1768193759048,
      "data": {
        "make": "Toyota",
        "model": "Camry"
      }
    }
    ```
  </Tab>

  <Tab title="Failure Payload">
    This payload is sent if the update fails (for example, if a call is currently active for the lead).

    ```json theme={null}
    {
      "action_type": "update",
      "updateId": "65e4b2d9f1a2...",
      "success": false,
      "error": "Lead update is not allowed while a call is in progress for this lead",
      "leadId": "696102a4b8...",
      "referenceId": "AB123456789",
      "timestamp": 1768193759048,
      "data": null
    }
    ```
  </Tab>
</Tabs>