Initiate Lead
curl --request POST \
--url https://crm.uservox.ai/api/v1/leads/initiate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"leadId": "<string>",
"lead": {
"projectId": "<string>",
"processId": "<string>",
"groupId": "<string>",
"phone": "<string>",
"email": "<string>",
"name": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"referenceId": "<string>",
"metadata": {}
},
"init": true
}
'import requests
url = "https://crm.uservox.ai/api/v1/leads/initiate"
payload = {
"leadId": "<string>",
"lead": {
"projectId": "<string>",
"processId": "<string>",
"groupId": "<string>",
"phone": "<string>",
"email": "<string>",
"name": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"referenceId": "<string>",
"metadata": {}
},
"init": True
}
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>',
lead: {
projectId: '<string>',
processId: '<string>',
groupId: '<string>',
phone: '<string>',
email: '<string>',
name: '<string>',
firstName: '<string>',
lastName: '<string>',
referenceId: '<string>',
metadata: {}
},
init: true
})
};
fetch('https://crm.uservox.ai/api/v1/leads/initiate', 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/initiate",
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>',
'lead' => [
'projectId' => '<string>',
'processId' => '<string>',
'groupId' => '<string>',
'phone' => '<string>',
'email' => '<string>',
'name' => '<string>',
'firstName' => '<string>',
'lastName' => '<string>',
'referenceId' => '<string>',
'metadata' => [
]
],
'init' => true
]),
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/initiate"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\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/initiate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://crm.uservox.ai/api/v1/leads/initiate")
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 \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"_id": "<string>",
"name": "<string>",
"phone": "<string>",
"email": "<string>",
"projectId": "<string>",
"processId": "<string>",
"referenceId": "<string>",
"currentState": "<string>",
"metadata": {},
"createdAt": "<string>",
"updatedAt": "<string>"
}Leads
Initiate Lead
Create or validate a lead and optionally start initialization for calling
POST
/
leads
/
initiate
Initiate Lead
curl --request POST \
--url https://crm.uservox.ai/api/v1/leads/initiate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"leadId": "<string>",
"lead": {
"projectId": "<string>",
"processId": "<string>",
"groupId": "<string>",
"phone": "<string>",
"email": "<string>",
"name": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"referenceId": "<string>",
"metadata": {}
},
"init": true
}
'import requests
url = "https://crm.uservox.ai/api/v1/leads/initiate"
payload = {
"leadId": "<string>",
"lead": {
"projectId": "<string>",
"processId": "<string>",
"groupId": "<string>",
"phone": "<string>",
"email": "<string>",
"name": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"referenceId": "<string>",
"metadata": {}
},
"init": True
}
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>',
lead: {
projectId: '<string>',
processId: '<string>',
groupId: '<string>',
phone: '<string>',
email: '<string>',
name: '<string>',
firstName: '<string>',
lastName: '<string>',
referenceId: '<string>',
metadata: {}
},
init: true
})
};
fetch('https://crm.uservox.ai/api/v1/leads/initiate', 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/initiate",
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>',
'lead' => [
'projectId' => '<string>',
'processId' => '<string>',
'groupId' => '<string>',
'phone' => '<string>',
'email' => '<string>',
'name' => '<string>',
'firstName' => '<string>',
'lastName' => '<string>',
'referenceId' => '<string>',
'metadata' => [
]
],
'init' => true
]),
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/initiate"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\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/initiate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://crm.uservox.ai/api/v1/leads/initiate")
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 \"lead\": {\n \"projectId\": \"<string>\",\n \"processId\": \"<string>\",\n \"groupId\": \"<string>\",\n \"phone\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"referenceId\": \"<string>\",\n \"metadata\": {}\n },\n \"init\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"_id": "<string>",
"name": "<string>",
"phone": "<string>",
"email": "<string>",
"projectId": "<string>",
"processId": "<string>",
"referenceId": "<string>",
"currentState": "<string>",
"metadata": {},
"createdAt": "<string>",
"updatedAt": "<string>"
}Rate Limits:
- Request Rate: ~100 requests per 5 seconds per project
- Duplicate Detection: More than 5 duplicate submissions in 60 seconds will block the API key for 60 minutes
Body Parameters
string
Existing lead ID to validate (required if
lead not provided)object
New lead object (required if
leadId not provided)Show Lead Object Properties
Show Lead Object Properties
string
required
MongoDB ObjectId of the project
string
required
MongoDB ObjectId of the process
string
Optional ID to group leads for analytics
string
Phone number (required if email not provided)
string
Email address (required if phone not provided)
string
Full name (required if firstName not provided)
string
First name (required if name not provided)
string
Last name
string
External reference ID for tracking
object
Additional metadata
boolean
default:"true"
Whether to initialize the lead for calling
Response
boolean
Indicates if the request was successful
string
MongoDB ObjectId of the lead
string
Lead’s name
string
Phone number
string
Email address
string
Project ID
string
Process ID
string
External reference ID
string
Current state of the lead
object
Lead metadata
string
ISO 8601 timestamp of creation
string
ISO 8601 timestamp of last update
Error Responses
-
400 Bad Request
- Missing body
- Returned when neither
leadIdnorleadis provided. - Example:
{ "error": "Either leadId or lead object is required" }
- Returned when neither
- Missing projectId
- Returned when creating a new lead without
lead.projectId. - Example:
{ "error": "projectId is required in lead object" }
- Returned when creating a new lead without
- Validation errors / bad leads
- Returned when the lead fails validation during creation or duplicate checks.
- Typical messages include:
"A call attempt has already been made to this phone number for this project""Phone number contains repeating digits pattern""already exists for this project and process"
- These indicate a bad/invalid lead. Do not retry these leads via this API.
- Recommended behavior:
- Mark the lead as invalid in your system.
- Fix the underlying data (phone number, process, etc.) before attempting again as a new lead.
- Missing body
-
403 Forbidden
- Returned when
lead.projectIddoes not match the authenticated project for the API key. - Example:
{ "error": "projectId does not match authenticated project" }
- Returned when
-
429 Too Many Requests
- Returned when duplicate protection blocks the API key due to too many duplicate submissions.
- Example response:
{ "success": false, "error": "...temporarily blocked..." } - Do not retry the same bad/duplicate leads.
- Recommended behavior:
- Stop sending further requests from the offending source.
- Investigate and fix the duplication issue before resuming traffic.
-
500 Internal Server Error
- Unexpected server-side error.
- Safe to retry with exponential backoff only for 5xx responses (not for 4xx).
Retry Guidance
- Do not retry bad leads
- Any 400 response with validation/duplicate messages (as above) should be treated as a permanent failure for that payload.
- Re-sending the same bad lead can:
- Trigger duplicate-protection rate limits.
- Lead to
429blocks for your API key.
- When to retry
- It is acceptable to implement retries (with backoff) for:
- Network errors.
- 5xx responses (
500and other server errors).
- Do not automatically retry on 4xx responses; fix the request or underlying data instead.
- It is acceptable to implement retries (with backoff) for:
