Quickstart

This walkthrough takes you from zero to a predictive-dial campaign with one lead queued, using either curl or an SDK.

1. Get an API key

Log into app.yotel.in as a tenant admin

You need the api_keys:manage permission (TENANT_ADMIN role).

Navigate to /developer/keys

Click Issue key. Give it a label like “Quickstart test”.

Copy the key immediately

The full yt_test_… value is shown once. We store only a hash — if you lose the key you’ll need to issue a new one.

Start with a test key (yt_test_…). Test keys behave identically to live keys at the API surface — they create campaigns, push leads, fire webhooks — but never actually dial the PSTN. Use live keys (yt_live_…) only once your integration is reviewed.

2. Create a campaign

curl -X POST https://api.yotel.in/api/v1/campaigns \
  -H "Authorization: Bearer $YOTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart demo",
    "dial_mode": "predictive",
    "predictive_target_abandon": 0.02
  }'

import yotel

client = yotel.Client(api_key=os.environ["YOTEL_KEY"])
campaign = client.campaigns.create(
    name="Quickstart demo",
    dial_mode="predictive",
    predictive_target_abandon=0.02,
)
print(campaign.id)

import { YotelClient } from "@yotel/client";

const client = new YotelClient({ apiKey: process.env.YOTEL_KEY! });
const campaign = await client.campaigns.create({
  name: "Quickstart demo",
  dial_mode: "predictive",
  predictive_target_abandon: 0.02,
});
console.log(campaign.id);

Every successful response carries rate-limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

3. Push a lead

curl -X POST \
  https://api.yotel.in/api/v1/campaigns/$CAMPAIGN_ID/leads \
  -H "Authorization: Bearer $YOTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9876543210",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "metadata": {"crm_id": "A-9912"}
  }'

lead = client.leads.create(
    campaign_id=campaign.id,
    phone="9876543210",
    name="Priya Sharma",
    email="priya@example.com",
    metadata={"crm_id": "A-9912"},
)

const lead = await client.leads.create({
  campaign_id: campaign.id,
  phone: "9876543210",
  name: "Priya Sharma",
  email: "priya@example.com",
  metadata: { crm_id: "A-9912" },
});

For bulk, use the :bulk suffix — up to 500 leads in one call:

curl -X POST \
  https://api.yotel.in/api/v1/campaigns/$CID/leads:bulk \
  -H "Authorization: Bearer $YOTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone":"98...1"},{"phone":"98...2"}]}'

Webhooks are managed from the dashboard (not the /api/v1/* path). Go to app.yotel.in/developer/webhooks → New subscription.

Choose the events you care about:

call.ended — every completed call with disposition + recording URL
campaign.paused — fired on both manual and auto-pause (check data.source)
lead.completed — lead reaches a terminal state

On create, you’ll get a signing_secret (shown once). Store it; you’ll need it to verify signatures.

5. Test the integration

DND-scrub your leads

Predictive campaigns refuse to start until every lead is scrubbed against the TRAI registry. Run POST /api/campaigns/{id}/scrub (or use the dashboard).

Start the campaign

POST /api/campaigns/{id}/start. Because your key is yt_test_…, the dialer registers the intent but doesn’t originate to PSTN.

Watch the webhook log

Your dashboard’s webhooks page shows every delivery with HTTP status + response snippet. If signatures don’t verify, the customer-side issue is usually clock skew — see troubleshooting.

Done

You’ve:

Issued an API key
Created a predictive campaign with custom tunables
Pushed a lead
Optionally subscribed a webhook

Next: read Authentication for scope + rotation, then Webhooks for event subscription in detail.

Get started

OAuth

Core concepts

Voice agents

SDKs

Integrations

1. Get an API key

2. Create a campaign

3. Push a lead

5. Test the integration

Done

​1. Get an API key

​2. Create a campaign

​3. Push a lead

​4. Subscribe a webhook (optional)

​5. Test the integration

​Done

1. Get an API key

2. Create a campaign

3. Push a lead

4. Subscribe a webhook (optional)

5. Test the integration

Done