Skip to Content
CallMitraDocs

Leads and callbacks

Create and update leads, store your own fields, push leads from forms, and follow the callbacks your agents book.

A lead is one person your agents can call. Campaigns dial leads, calls are logged against them, and the details you store on a lead become variables your agent can speak.

The lead model

GET /api/v1/leads/{lead_id} returns the full lead. The fields you will use most:

FieldMeaning
idCallMitra lead ID.
name, phone, email, company, titleCore contact fields. phone is stored in E.164 (see Phone numbers).
statusPipeline stage. One of your workspace's pipeline keys; new by default.
source, leadSourceIdWhere the lead came from, and the lead source it belongs to.
externalIdYour own ID for the lead, up to 64 characters. Unique inside a lead source.
attributesYour own fields, as an object of key and value.
attributeIssuesValues that did not fit their field type: { key: { raw, reason, at } }.
tagsFree-form labels.
assignedToUserId, assigneeNameTeammate who owns the lead.
campaignIds, campaignNamesCampaigns the lead is on.
callStatus, callAttempts, lastCallAttempt, lastContactDateCalling history at a glance.
nextCallScheduledTime of the lead's next booked callback, if any.
dncOptOut, dncReason, dncUpdatedAtDo-not-call state.
notesCount, pinnedNotePreviewNotes summary. notes is deprecated; use notes.
createdAt, updatedAtTimestamps.

Create a lead

POST /api/v1/leads/ takes name, phone, email, company, title, status, source, leadSourceId, campaignIds, attributes, and notes (saved as the lead's first note). Send an Idempotency-Key header so a retried request does not create the lead twice.

curl -X POST https://api.callmitra.ai/api/v1/leads/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-1042-create" \
  -d '{
    "name": "Asha Rao",
    "phone": "9876543210",
    "email": "[email protected]",
    "attributes": { "plan": "Gold", "renewal_date": "2026-12-01" }
  }'

The phone above is saved as +919876543210. An unknown status is saved as new and reported in the response's warnings. CallMitra sends a lead.created webhook.

Create does not deduplicate

createLead always creates a new lead. It does not match on phone, and it does not accept externalId. To keep one lead per record in your system, store our id, or set externalId with an update and look the lead up before creating. The lead intake webhook does deduplicate.

Update a lead

PUT /api/v1/leads/{lead_id} is a partial update: send only the fields you change.

  • externalId accepts a string or a number. It is trimmed and limited to 64 characters.
  • tags and campaignIds replace the current lists. Campaigns you cannot access are skipped.
  • attributes merges into the current object. Set a key to null to clear it.
  • timezone takes an IANA name such as Asia/Kolkata; an invalid name returns 422.
  • additionalData is refused with 422. Send attributes instead.

To avoid overwriting someone else's edit, send the lead's updatedAt in an If-Match header. If the lead changed since you read it, you get 409 lead_changed. CallMitra sends a lead.updated webhook after each update.

DELETE /api/v1/leads/{lead_id} removes the lead permanently. Its calls stay in your call history. POST /api/v1/leads/bulk applies one action (status, assign, tag, untag, dnc, undnc, delete) to 1 to 500 lead IDs at once.

List leads with GET /api/v1/leads/. See Pagination for page and cursor options.

Lead fields and attributes

Your workspace keeps a catalogue of lead fields. GET /api/v1/lead-fields/catalog returns it, sorted by label:

{
  "fields": [
    { "id": "6f1c…", "key": "plan", "label": "Plan", "valueType": "text" },
    { "id": "8a2d…", "key": "renewal_date", "label": "Renewal date", "valueType": "date" }
  ]
}

Each field's key is the key you use in a lead's attributes. valueType is one of text, number, boolean, list, date or datetime.

curl https://api.callmitra.ai/api/v1/lead-fields/catalog \
  -H "X-API-Key: $CALLMITRA_API_KEY"

How attributes are written:

  • Keys are turned into lowercase snake_case (letters, digits and _). Renewal Date becomes renewal_date.
  • name, phone, email, company and title fill the matching core field when that field is empty.
  • Reserved keys are ignored: agent_name, caller_name, campaign_name, callback_number, timestamp, source, id, row, notes.
  • A key that is not in the catalogue creates a new text field, flagged for review in the console.
  • A value that does not fit its field type is never rejected. It is kept in attributeIssues and reported in warnings, so you can fix it later.

Agent variables

Your agent's prompt and first message can use {{variable}} placeholders. On every call, CallMitra fills them from the lead:

  • Core fields: {{lead_name}} (also {{customer_name}}), {{lead_first_name}}, {{lead_last_name}}, {{lead_phone}}, {{lead_email}}, {{lead_company}}.
  • Context: {{campaign_name}}, {{agent_name}}.
  • Every attribute key: plan becomes {{plan}}. Fields marked sensitive or archived are never sent to the agent.
  • Answers your agent captured on earlier calls with the same lead.

A campaign whose agent uses a placeholder that no lead can fill does not start: you get 422 campaign_not_ready listing the unresolved placeholders.

Phone numbers

createLead and updateLead normalise phone to E.164 before saving. An empty phone is allowed.

  1. If the value holds several numbers separated by , / | or ;, the first one is used. A trailing .0 (from spreadsheets) is removed, and spaces, dashes and brackets are ignored.
  2. A number that starts with + or 00 is international. After dropping leading zeros, a 10-digit number starting with 6 to 9 becomes +91…; any other 8 to 15 digit number is kept as + and its digits.
  3. Without + or 00, leading zeros are dropped. A 10-digit number becomes +91…. A number starting with 91 followed by 7 to 11 digits is kept as +91….
  4. Anything else is refused with 422 invalid_phone_number on param: "phone".
You sendSaved as
9876543210+919876543210
09876543210+919876543210
919876543210+919876543210
+44 20 7946 0958+442079460958
12345422 invalid_phone_number

Numbers outside India

Send numbers from other countries with + or 00 and the country code. Without it, a 10-digit number is read as an Indian mobile.

Do-not-call

Leads on your do-not-call list are never dialed. Add numbers with POST /api/v1/leads/dnc (phones as a newline- or comma-separated string, optional reason), list them with GET /api/v1/leads/dnc, and remove one with DELETE /api/v1/leads/dnc/{lead_id}. Only Indian mobile numbers are accepted; if none are valid you get 422 dnc_no_valid_numbers. Calling a number on the list returns 409 number_on_dnc. See Calling in India for the rules.

Notes and timeline

Both are cursor lists; see Pagination.

Callbacks

A callback is a call CallMitra places to a lead at a set time. Callbacks are booked:

  • by your agent during a call, when the agent has the schedule-callback tool turned on and the caller asks to be called later (source is ai_tool);
  • from the call analysis after a call;
  • by your team in the console, or from a CSV import;
  • by reminder rules (kind is reminder, source is rule).

Rules a callback follows:

  • A lead has at most one active callback. A newer one replaces a pending one.
  • Callbacks can be booked up to 60 days ahead. If the time falls outside the campaign's calling window, dialAt moves to the next allowed time and shifted is true.
  • A callback that is not answered is retried after 30 minutes, up to the campaign's callback attempt limit (2 by default, 1 to 5).
  • While a lead has a callback booked (nextCallScheduled), bulk campaign dialing skips it.

List callbacks

GET /api/v1/callbacks lists callbacks, soonest dialAt first.

ParameterMeaning
statusComma-separated statuses, or all. Default pending,queued,dialing (still to happen).
kindcallback or reminder.
leadId, campaignId, agentIdOnly callbacks for this lead, campaign or agent. Must be UUIDs.
dateFrom, dateToISO 8601 bounds on dialAt. A time without an offset is read as UTC.
limit, offsetPage size (default 50, 1 to 200) and items to skip.

Statuses: pending, queued, dialing, done, failed, cancelled, expired. An unknown status or a bad UUID or date returns 422 parameter_invalid.

curl "https://api.callmitra.ai/api/v1/callbacks?leadId=LEAD_ID&status=all" \
  -H "X-API-Key: $CALLMITRA_API_KEY"

Each item carries id, leadId, leadName, leadPhone, campaignId, campaignName, agentId, kind, channel, purpose, note, source, status, dueAt (the time asked for), dialAt (the time it will be dialed), dialAtLocal, shifted, timezone, attempts, maxAttempts, lastOutcome, callId (the callback call), originCallId (the call that booked it) and createdAt. total counts every match.

To hear about callbacks as they happen, subscribe to callback.scheduled, callback.completed and callback.failed. See Webhook events.

Push leads from forms

A lead intake webhook lets a form, ad platform or your own system add leads without an API key. Each integration has its own URL and key. Send the lead to POST /api/v1/webhooks/leads/{webhook_token} with the key in the X-Lead-Webhook-Key header (or ?key= in the URL).

The body is a flat JSON object:

  • name, phone, email, company, title fill the core fields. A lead needs phone or email.
  • lead_id (or leadId, leadgen_id, id) is your ID for the lead. It is saved as externalId.
  • Any other key and simple value is saved in attributes.
  • Google Ads lead forms (user_column_data) and Meta lead ads (field_data) payloads are understood as sent.
  • is_test: true checks your setup without creating a lead.
curl -X POST https://api.callmitra.ai/api/v1/webhooks/leads/WEBHOOK_TOKEN \
  -H "X-Lead-Webhook-Key: $LEAD_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lead_id": "form-88213", "name": "Asha Rao", "phone": "+919876543210", "city": "Pune" }'

A new lead returns { "success": true, "leadId": "…", "externalLeadId": "form-88213", "campaignAttached": true }. When the integration is linked to a campaign, the lead is added to it.

Repeats are safe. The webhook deduplicates per integration on lead_id; without one, on the source, phone, email, name and form. A repeat returns { "success": true, "duplicate": true, "externalLeadId": "…" } and creates nothing.

StatusBodyWhy
400{ "success": false, "error": "Lead must include phone or email" }No phone and no email.
401{ "success": false, "error": "invalid webhook key" }Missing or wrong webhook key.
404{ "success": false, "error": "invalid token" } or "integration not found"Unknown webhook token.
429{ "success": false, "error": "rate limit" }More than 300 requests a minute from one IP address.
500{ "success": false, … }Our error. Retry; deduplication absorbs repeats.

Phone numbers on the intake webhook

The intake webhook does not refuse a lead for its phone format. It saves the number with a + prefix, so send it in E.164.

On this page