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>"
}
'import requests
url = "https://crm.uservox.ai/api/v1/leads/update"
payload = {
"leadId": "<string>",
"referenceId": "<string>",
"projectId": "<string>",
"processId": "<string>",
"metadata": {},
"name": "<string>",
"targetState": "<string>",
"disposition": "<string>",
"userId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
leadId: '<string>',
referenceId: '<string>',
projectId: '<string>',
processId: '<string>',
metadata: {},
name: '<string>',
targetState: '<string>',
disposition: '<string>',
userId: '<string>'
})
};
fetch('https://crm.uservox.ai/api/v1/leads/update', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://crm.uservox.ai/api/v1/leads/update",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => '<string>',
'referenceId' => '<string>',
'projectId' => '<string>',
'processId' => '<string>',
'metadata' => [
],
'name' => '<string>',
'targetState' => '<string>',
'disposition' => '<string>',
'userId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://crm.uservox.ai/api/v1/leads/update"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://crm.uservox.ai/api/v1/leads/update")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://crm.uservox.ai/api/v1/leads/update")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>"
}Leads
Update Lead
Update a lead’s metadata and optionally transition to a new state
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>"
}
'import requests
url = "https://crm.uservox.ai/api/v1/leads/update"
payload = {
"leadId": "<string>",
"referenceId": "<string>",
"projectId": "<string>",
"processId": "<string>",
"metadata": {},
"name": "<string>",
"targetState": "<string>",
"disposition": "<string>",
"userId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
leadId: '<string>',
referenceId: '<string>',
projectId: '<string>',
processId: '<string>',
metadata: {},
name: '<string>',
targetState: '<string>',
disposition: '<string>',
userId: '<string>'
})
};
fetch('https://crm.uservox.ai/api/v1/leads/update', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://crm.uservox.ai/api/v1/leads/update",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => '<string>',
'referenceId' => '<string>',
'projectId' => '<string>',
'processId' => '<string>',
'metadata' => [
],
'name' => '<string>',
'targetState' => '<string>',
'disposition' => '<string>',
'userId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://crm.uservox.ai/api/v1/leads/update"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://crm.uservox.ai/api/v1/leads/update")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://crm.uservox.ai/api/v1/leads/update")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"metadata\": {},\n \"name\": \"<string>\",\n \"targetState\": \"<string>\",\n \"disposition\": \"<string>\",\n \"userId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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
string
MongoDB ObjectId of the lead (required if not using referenceId)
string
External reference ID (requires projectId and processId)
string
Required when using referenceId
string
Required when using referenceId
object
Metadata object to merge with existing metadata
string
Update the lead’s name
string
Target state to transition the lead to (e.g., “interested”, “lost”, “followup_2”)
string
Disposition reason (used with targetState “interested” or “lost”)
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
boolean
Indicates if the update request was successfully accepted
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.- Success Payload
- Failure Payload
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"
}
}
This payload is sent if the update fails (for example, if a call is currently active for the lead).
{
"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
}
⌘I
