Skip to main content
POST
/
leads
/
update
Update Lead
curl --request POST \
  --url https://crm.uservox.ai/api/v1/leads/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leadId": "<string>",
  "referenceId": "<string>",
  "projectId": "<string>",
  "processId": "<string>",
  "metadata": {},
  "name": "<string>",
  "targetState": "<string>",
  "disposition": "<string>",
  "userId": "<string>"
}
'
{
  "success": true,
  "message": "<string>"
}

​
Overview

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.

​
Body Parameters

​
leadId
string
MongoDB ObjectId of the lead (required if not using referenceId)
​
referenceId
string
External reference ID (requires projectId and processId)
​
projectId
string
Required when using referenceId
​
processId
string
Required when using referenceId
​
metadata
object
Metadata object to merge with existing metadata
​
name
string
Update the lead’s name
​
targetState
string
Target state to transition the lead to (e.g., “interested”, “lost”, “followup_2”)
​
disposition
string
Disposition reason (used with targetState “interested” or “lost”)
​
userId
string
User ID for audit logging
If metadata is not provided, all other fields (except leadId, referenceId, projectId, processId, targetState, name, disposition, userId) will be merged into metadata.

​
Response

​
success
boolean
Indicates if the update request was successfully accepted
​
message
string
Confirmation message (e.g., “Lead update initiated”)

​
Webhook Notifications

Once the asynchronous update job finishes processing, a webhook will be sent to the callback URLs configured in the Lead’s Process.
This payload is sent when the lead is successfully updated and transitioned (if requested).
{
  "action_type": "update",
  "updateId": "65e4b2d9f1a2...",
  "success": true,
  "error": null,
  "leadId": "696102a4b8...",
  "referenceId": "AB123456789",
  "timestamp": 1768193759048,
  "data": {
    "make": "Toyota",
    "model": "Camry"
  }
}