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.

One endpoint, two spellings. Every request field below accepts our canonical name and the common CRM aliases in the Aliases column — you don’t need to rename columns before pushing. The Salesforce lead push guide shows the same endpoint using the CRM spellings (lead_id / first_name / mobile); those pages are not describing two different APIs.If a request carries both spellings of one field, the canonical name wins (name beats first_name).Aliases apply to the request only. Every response — and every webhook — uses the canonical names.

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",
    "salesforce_lead_id": "00Qfv00000NZA2UEAX",
    "metadata": {"plan": "enterprise", "source": "website"}
  }'

# Identical request — `mobile`/`first_name`/`lead_id` are aliases, not a
# different endpoint. Push whichever spelling your CRM already produces.
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 '{
    "mobile": "9876543210",
    "first_name": "Priya Sharma",
    "lead_id": "00Qfv00000NZA2UEAX"
  }'

lead = client.leads.create(
    campaign_id="campaign_id",
    phone="9876543210",
    name="Priya Sharma",
    email="priya@example.com",
    salesforce_lead_id="00Qfv00000NZA2UEAX",
    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",
  salesforce_lead_id: "00Qfv00000NZA2UEAX",
  metadata: { plan: "enterprise", source: "website" },
});
console.log(lead.id);

Request body

Field	Aliases	Type	Required	Description
`phone`	`mobile`, `phone_number`, `mobile_number`	string	Yes	Indian phone number (10 digits; optional `0` or `91` prefix is stripped). 5–20 chars.
`salesforce_lead_id`	`lead_id`, `sf_lead_id`	string	No	External Salesforce Lead id — a 15/18-char `00Q…` id or a CRM-native `L-XXXXXXXX` id. ≤64 chars. Used to key the CRM copilot screen-pop and as a second dedup key alongside the phone number (a re-push with a corrected number is still recognized as the same lead).
`name`	`first_name`, `full_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.

Privacy (PII-strict tenants). If your tenant is configured for strict PII handling, every response — the single-push response, every row of a bulk response, even an invalid row — echoes a masked phone (••••3210) instead of the number you sent. The plaintext number is never returned once ingested. This is not a bug in your integration; it’s the same masking GET/list endpoints apply for that tenant.Every lead response also carries phone_last4 — the last four digits, plaintext, for every tenant. On a strict tenant it is the only stable partial identifier available (phone is masked and, once the lead reaches a terminal status, dropped entirely), so key your reconciliation on salesforce_lead_id and display phone_last4.

Duplicate lead → `409`

A single push checks the campaign for an existing lead matching this one by phone hash or by salesforce_lead_id — either match is enough. If one is found, the push is rejected outright rather than silently creating a second row:

409 Conflict

{
  "detail": "Duplicate lead in campaign",
  "id": "lead_abc",
  "lead_id": "lead_abc",
  "salesforce_lead_id": "00Qfv00000NZA2UEAX",
  "status": "pending",
  "phone_purged": false
}

id is the existing Yotel lead’s id; salesforce_lead_id is its existing SF id (null if that lead has none). Neither the request nor the response echoes a phone number.

lead_id means two different things in this API — read id instead.In a request body, and in every bulk result row, lead_id is the CRM lead id (an alias for salesforce_lead_id). In this 409 body it has always been Yotel’s own lead id. A client that joins on lead_id across the single and bulk paths is joining two different entities.The 409 now also returns that value as id — the same spelling, with the same meaning, that bulk result rows use. Read id here and salesforce_lead_id for the CRM id. lead_id is retained for backwards compatibility and should be treated as deprecated in this response.

status is the existing lead’s status and phone_purged says whether its number has been dropped. A lead that reaches dnd has its stored number purged on the spot; one that reaches completed, failed, busy or no_answer keeps it for the tenant’s retention window (default 30 days) and is purged after that. The dedup key is kept either way, so a re-push of a completed or dnd lead matches and the detail names the status. That lead will not be dialed again; re-pushing it is a no-op, not a re-queue. A re-push of an exhausted lead (failed, busy, no_answer — its attempt budget ran out) is a request to try again: it returns 201 and inserts a fresh, freshly scrubbed row.

If you’re re-sending the exact same push after a timeout or a retry — not intentionally re-pushing an existing lead — that’s what Idempotency-Key is for (see Idempotency): it returns your original 201 response instead of a 409, because Yotel recognizes the retry before dedup logic ever runs. Reach for Idempotency-Key on retries; expect (and handle) 409 when the lead genuinely already exists.

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" \
  -H "Idempotency-Key: 8a4c1f3e-9c21-4b7d-8e8a-9b1e2f3a4c5d" \
  -d '{
    "leads": [
      {"lead_id": "00Qfv00000NZA2UEAX", "first_name": "Priya Sharma", "mobile": "9876543210"},
      {"phone": "9123456789", "name": "Raj Patel"},
      {"phone": "12345", "name": "Bad Number"}
    ]
  }'

result = client.leads.bulk(
    campaign_id="campaign_id",
    leads=[
        {"phone": "9876543210", "name": "Priya Sharma", "salesforce_lead_id": "00Qfv00000NZA2UEAX"},
        {"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", salesforce_lead_id: "00Qfv00000NZA2UEAX" },
    { phone: "9123456789", name: "Raj Patel" },
  ],
});
console.log(`Added: ${result.valid}, Dupes: ${result.duplicates}`);

Bulk pushes are the one place we’d most recommend the Idempotency-Key header above — see Idempotency. A timed-out 500-lead batch is expensive to diagnose by hand; a retried request with the same key just returns the original result instead of re-processing.

Response

{
  "total": 3,
  "valid": 2,
  "invalid": 1,
  "duplicates": 0,
  "results": [
    {"lead_id": "00Qfv00000NZA2UEAX", "phone": "9876543210", "status": "added", "id": "lead_abc"},
    {"lead_id": null, "phone": "9123456789", "status": "added", "id": "lead_def"},
    {"lead_id": null, "phone": "••••2345", "status": "invalid"}
  ]
}

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 hash or by `salesforce_lead_id`, so a re-push of the same SF lead with a corrected number is still recognized)
`results`	array	Per-lead outcome: `lead_id` (the `salesforce_lead_id` you submitted, or `null`), `phone`, `status` (`added`, `duplicate`, or `invalid`), and `id` (the Yotel lead id — present only on `added`)

Privacy. A results row with status: "invalid" is always masked (••••2345, or null if the input had no recognizable digits at all) — on every tenant, not only PII-strict ones. We never echo a raw number back for a row that failed validation. On a PII-strict tenant, duplicate and added rows are masked too; on a standard tenant those two carry the plaintext number, same as GET responses do for that tenant.

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
`409`	Duplicate lead in campaign (single push only — bulk counts duplicates in `results` instead, see above)
`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

Duplicate lead → `409`

Bulk push leads

Response

DND scrubbing

Errors

​Push a single lead

​Request body

​Duplicate lead → 409

​Bulk push leads

​Response

​DND scrubbing

​Errors

Push a single lead

Request body

Duplicate lead → `409`

Bulk push leads

Response

DND scrubbing

Errors