Skip to main content
Leads are phone numbers (with optional metadata) attached to a campaign. All leads are automatically scrubbed against the TRAI DNC registry at ingestion time — leads flagged as DND are marked but not rejected.

​
Push a single lead

curl -X POST https://api.yotel.in/api/v1/campaigns/{campaign_id}/leads \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9876543210",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "metadata": {"plan": "enterprise", "source": "website"}
  }'

​
Request body

FieldTypeRequiredDescription
phonestringYesIndian phone number (10 digits; optional 0 or 91 prefix is stripped). 5–20 chars.
namestringNoLead display name
emailstringNoLead email address
metadataobjectNoArbitrary key-value pairs passed to webhooks and the voice agent metadata frame
Scope: leads:write  |  Status: 201 Created
Phone numbers are validated as Indian numbers. International numbers are rejected with a 422 validation error.

​
Bulk push leads

Push up to 500 leads in a single request. Invalid or duplicate leads are counted in the response but do not fail the request. 
curl -X POST https://api.yotel.in/api/v1/campaigns/{campaign_id}/leads:bulk \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {"phone": "9876543210", "name": "Priya Sharma"},
      {"phone": "9123456789", "name": "Raj Patel"},
      {"phone": "invalid", "name": "Bad Number"}
    ]
  }'

​
Response

{
  "total": 3,
  "valid": 2,
  "invalid": 1,
  "duplicates": 0,
  "results": [
    {"phone": "9876543210", "status": "added", "id": "lead_abc"},
    {"phone": "9123456789", "status": "added", "id": "lead_def"},
    {"phone": "invalid", "status": "invalid", "id": null}
  ]
}
Scope: leads:write  |  Status: 200 OK
Response fieldTypeDescription
totalintegerNumber of leads submitted
validintegerLeads successfully added
invalidintegerLeads that failed phone validation
duplicatesintegerLeads already in this campaign (by phone)
resultsarrayPer-lead outcome with phone, status, and id (null for invalid/duplicate)

​
DND scrubbing

Every lead is automatically checked against the TRAI DNC registry at ingestion. Leads flagged as DND get dnd_checked: true and dnd_clean: false — they will not be dialed but remain visible in the campaign for audit. This is a regulatory requirement and cannot be disabled.

​
Errors

StatusCondition
404Campaign not found or belongs to another tenant
422Phone number validation failed (single lead)