Skip to main content
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
}
'
{
  "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

​
leadId
string
Existing lead ID to validate (required if lead not provided)
​
lead
object
New lead object (required if leadId not provided)
​
init
boolean
default:"true"
Whether to initialize the lead for calling

​
Response

​
success
boolean
Indicates if the request was successful
​
_id
string
MongoDB ObjectId of the lead
​
name
string
Lead’s name
​
phone
string
Phone number
​
email
string
Email address
​
projectId
string
Project ID
​
processId
string
Process ID
​
referenceId
string
External reference ID
​
currentState
string
Current state of the lead
​
metadata
object
Lead metadata
​
createdAt
string
ISO 8601 timestamp of creation
​
updatedAt
string
ISO 8601 timestamp of last update

​
Error Responses

  • 400 Bad Request
    • Missing body
      • Returned when neither leadId nor lead is provided.
      • Example: { "error": "Either leadId or lead object is required" }
    • Missing projectId
      • Returned when creating a new lead without lead.projectId.
      • Example: { "error": "projectId is required in lead object" }
    • 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.
  • 403 Forbidden
    • Returned when lead.projectId does not match the authenticated project for the API key.
    • Example: { "error": "projectId does not match authenticated project" }
  • 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 429 blocks for your API key.
  • When to retry
    • It is acceptable to implement retries (with backoff) for:
      • Network errors.
      • 5xx responses (500 and other server errors).
    • Do not automatically retry on 4xx responses; fix the request or underlying data instead.