Leads

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"}
  }'

lead = client.leads.create(
    campaign_id="campaign_id",
    phone="9876543210",
    name="Priya Sharma",
    email="priya@example.com",
    metadata={"plan": "enterprise", "source": "website"},
)
print(lead.id)

const lead = await client.leads.create({
  campaign_id: "campaign_id",
  phone: "9876543210",
  name: "Priya Sharma",
  email: "priya@example.com",
  metadata: { plan: "enterprise", source: "website" },
});
console.log(lead.id);

Request body

Field	Type	Required	Description
`phone`	string	Yes	Indian phone number (10 digits; optional `0` or `91` prefix is stripped). 5–20 chars.
`name`	string	No	Lead display name
`email`	string	No	Lead email address
`metadata`	object	No	Arbitrary 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"}
    ]
  }'

result = client.leads.bulk(
    campaign_id="campaign_id",
    leads=[
        {"phone": "9876543210", "name": "Priya Sharma"},
        {"phone": "9123456789", "name": "Raj Patel"},
    ],
)
print(f"Added: {result.valid}, Dupes: {result.duplicates}, Invalid: {result.invalid}")

const result = await client.leads.bulk({
  campaign_id: "campaign_id",
  leads: [
    { phone: "9876543210", name: "Priya Sharma" },
    { phone: "9123456789", name: "Raj Patel" },
  ],
});
console.log(`Added: ${result.valid}, Dupes: ${result.duplicates}`);

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 field	Type	Description
`total`	integer	Number of leads submitted
`valid`	integer	Leads successfully added
`invalid`	integer	Leads that failed phone validation
`duplicates`	integer	Leads already in this campaign (by phone)
`results`	array	Per-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

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

Overview

Campaigns

Calls & Recordings

Agents

Voice Agents

AI Sessions

Webhook Management

API Keys

Leads

Push a single lead

Request body

Bulk push leads

Response

DND scrubbing

Errors

​Push a single lead

​Request body

​Bulk push leads

​Response

​DND scrubbing

​Errors

Push a single lead

Request body

Bulk push leads

Response

DND scrubbing

Errors