Skip to main content
GET
/
leads
/
get
Get Lead
curl --request GET \
  --url https://crm.uservox.ai/api/v1/leads/get \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": {
    "_id": "<string>",
    "name": "<string>",
    "phone": "<string>",
    "email": "<string>",
    "projectId": "<string>",
    "processId": "<string>",
    "referenceId": "<string>",
    "currentState": "<string>",
    "lastDisposition": "<string>",
    "metadata": {},
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "activities": [
      {}
    ]
  }
}
Rate Limits:
  • Request Rate: ~100 requests per 5 seconds per project (same as other lead APIs).
  • Heavy use of this endpoint (especially with masked=false) can be expensive; cache results when possible.

​
Query 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
​
masked
boolean
default:"false"
If true, masks phone number (all but last 4 digits)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The lead object with activities

​
Error Responses

  • 400 Bad Request
    • Missing identifier
      • Returned when neither leadId nor referenceId is provided.
      • Example: 
        {
  "success": false,
  "error": "Either leadId or referenceId is required"
}
    • Missing projectId/processId with referenceId
      • Returned when referenceId is provided without both projectId and processId.
      • Example: 
        {
  "success": false,
  "error": "projectId and processId are required when using referenceId"
}
  • 404 Not Found
    • Returned when no lead matches the provided identifiers.
    • Examples: 
      { "success": false, "error": "Lead with ID <leadId> not found" }
{ "success": false, "error": "Lead with referenceId <referenceId> not found" }
  • 429 Too Many Requests
    • Returned when project-level rate limits are exceeded for this endpoint.
    • Recommended behavior:
      • Back off and retry later with exponential backoff.
      • Avoid hot-loop polling; cache results on your side when possible.
  • 500 Internal Server Error
    • Unexpected server-side error.
    • Safe to retry with backoff; if it persists, contact support with request details.