# Leads and callbacks (/guides/leads)

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 [#the-lead-model]

[`GET /api/v1/leads/{lead_id}`](/api-reference/leads/getLead) returns the full lead. The fields you will use most:

| Field | Meaning |
| --- | --- |
| `id` | CallMitra lead ID. |
| `name`, `phone`, `email`, `company`, `title` | Core contact fields. `phone` is stored in E.164 (see [Phone numbers](#phone-numbers)). |
| `status` | Pipeline stage. One of your workspace's pipeline keys; `new` by default. |
| `source`, `leadSourceId` | Where the lead came from, and the lead source it belongs to. |
| `externalId` | Your own ID for the lead, up to 64 characters. Unique inside a lead source. |
| `attributes` | Your own fields, as an object of key and value. |
| `attributeIssues` | Values that did not fit their field type: `{ key: { raw, reason, at } }`. |
| `tags` | Free-form labels. |
| `assignedToUserId`, `assigneeName` | Teammate who owns the lead. |
| `campaignIds`, `campaignNames` | Campaigns the lead is on. |
| `callStatus`, `callAttempts`, `lastCallAttempt`, `lastContactDate` | Calling history at a glance. |
| `nextCallScheduled` | Time of the lead's next booked callback, if any. |
| `dncOptOut`, `dncReason`, `dncUpdatedAt` | Do-not-call state. |
| `notesCount`, `pinnedNotePreview` | Notes summary. `notes` is deprecated; use [notes](#notes-and-timeline). |
| `createdAt`, `updatedAt` | Timestamps. |

### Create a lead [#create-a-lead]

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

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
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": "asha@example.com",
    "attributes": { "plan": "Gold", "renewal_date": "2026-12-01" }
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/leads/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'crm-1042-create',
  },
  body: JSON.stringify({
    name: 'Asha Rao',
    phone: '9876543210',
    email: 'asha@example.com',
    attributes: { plan: 'Gold', renewal_date: '2026-12-01' },
  }),
});
const body = await res.json();
```
</Tab>

<Tab value="Python">
```python
import os, requests

res = requests.post(
    "https://api.callmitra.ai/api/v1/leads/",
    headers={
        "X-API-Key": os.environ["CALLMITRA_API_KEY"],
        "Idempotency-Key": "crm-1042-create",
    },
    json={
        "name": "Asha Rao",
        "phone": "9876543210",
        "email": "asha@example.com",
        "attributes": {"plan": "Gold", "renewal_date": "2026-12-01"},
    },
    timeout=30,
)
body = res.json()
```
</Tab>
</Tabs>

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`](/api-reference/webhooks/onLeadCreated) webhook.

<Callout type="warn" title="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](#push-leads-from-forms) does deduplicate.
</Callout>

### Update a lead [#update-a-lead]

[`PUT /api/v1/leads/{lead_id}`](/api-reference/leads/updateLead) 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`](/errors/lead_changed). CallMitra sends a [`lead.updated`](/api-reference/webhooks/onLeadUpdated) webhook after each update.

[`DELETE /api/v1/leads/{lead_id}`](/api-reference/leads/deleteLead) removes the lead permanently. Its calls stay in your call history. [`POST /api/v1/leads/bulk`](/api-reference/leads/bulkLeadAction) 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/`](/api-reference/leads/listLeads). See [Pagination](/pagination) for page and cursor options.

## Lead fields and attributes [#lead-fields-and-attributes]

Your workspace keeps a catalogue of lead fields. [`GET /api/v1/lead-fields/catalog`](/api-reference/leads/listLeadFields) returns it, sorted by label:

```json
{
  "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`.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl https://api.callmitra.ai/api/v1/lead-fields/catalog \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/lead-fields/catalog', {
  headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY },
});
const { fields } = await res.json();
```
</Tab>

<Tab value="Python">
```python
res = requests.get(
    "https://api.callmitra.ai/api/v1/lead-fields/catalog",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    timeout=30,
)
fields = res.json()["fields"]
```
</Tab>
</Tabs>

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 [#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`](/errors/campaign_not_ready) listing the unresolved placeholders.

## Phone numbers [#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`](/errors/invalid_phone_number) on `param: "phone"`.

| You send | Saved as |
| --- | --- |
| `9876543210` | `+919876543210` |
| `09876543210` | `+919876543210` |
| `919876543210` | `+919876543210` |
| `+44 20 7946 0958` | `+442079460958` |
| `12345` | `422 invalid_phone_number` |

<Callout title="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.
</Callout>

## Do-not-call [#do-not-call]

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

## Notes and timeline [#notes-and-timeline]

- **Notes.** [`GET /api/v1/leads/{lead_id}/notes`](/api-reference/lead-notes/listLeadNotes) lists a lead's notes, with pinned notes on the first page. Create, edit, pin and delete notes with the other [lead notes](/api-reference/lead-notes/createLeadNote) endpoints. An edit must send the note's `version`; if it changed, you get `409` [`lead_note_changed`](/errors/lead_note_changed). A lead can have at most 3 pinned notes ([`lead_note_pin_limit`](/errors/lead_note_pin_limit)).
- **Timeline.** [`GET /api/v1/leads/{lead_id}/timeline`](/api-reference/leads/getLeadTimeline) returns one feed of calls, WhatsApp messages, tickets, notes, changes and callbacks. Filter with `types`. The first page also lists upcoming callbacks.

Both are cursor lists; see [Pagination](/pagination).

## Callbacks [#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 [#list-callbacks]

[`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) lists callbacks, soonest `dialAt` first.

| Parameter | Meaning |
| --- | --- |
| `status` | Comma-separated statuses, or `all`. Default `pending,queued,dialing` (still to happen). |
| `kind` | `callback` or `reminder`. |
| `leadId`, `campaignId`, `agentId` | Only callbacks for this lead, campaign or agent. Must be UUIDs. |
| `dateFrom`, `dateTo` | ISO 8601 bounds on `dialAt`. A time without an offset is read as UTC. |
| `limit`, `offset` | Page 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`](/errors/parameter_invalid).

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl "https://api.callmitra.ai/api/v1/callbacks?leadId=LEAD_ID&status=all" \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const url = new URL('https://api.callmitra.ai/api/v1/callbacks');
url.searchParams.set('leadId', leadId);
url.searchParams.set('status', 'all');
const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } });
const { callbacks, total } = await res.json();
```
</Tab>

<Tab value="Python">
```python
res = requests.get(
    "https://api.callmitra.ai/api/v1/callbacks",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    params={"leadId": lead_id, "status": "all"},
    timeout=30,
)
data = res.json()
callbacks, total = data["callbacks"], data["total"]
```
</Tab>
</Tabs>

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`](/api-reference/webhooks/onCallbackScheduled), [`callback.completed`](/api-reference/webhooks/onCallbackCompleted) and [`callback.failed`](/api-reference/webhooks/onCallbackFailed). See [Webhook events](/webhooks/events).

## Push leads from forms [#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}`](/api-reference/lead-intake-webhook/pushLead) 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.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
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" }'
```
</Tab>

<Tab value="Node.js">
```js
await fetch(`https://api.callmitra.ai/api/v1/webhooks/leads/${webhookToken}`, {
  method: 'POST',
  headers: {
    'X-Lead-Webhook-Key': process.env.LEAD_WEBHOOK_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ lead_id: 'form-88213', name: 'Asha Rao', phone: '+919876543210', city: 'Pune' }),
});
```
</Tab>

<Tab value="Python">
```python
requests.post(
    f"https://api.callmitra.ai/api/v1/webhooks/leads/{webhook_token}",
    headers={"X-Lead-Webhook-Key": os.environ["LEAD_WEBHOOK_KEY"]},
    json={"lead_id": "form-88213", "name": "Asha Rao", "phone": "+919876543210", "city": "Pune"},
    timeout=30,
)
```
</Tab>
</Tabs>

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.

| Status | Body | Why |
| --- | --- | --- |
| `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. |

<Callout title="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.
</Callout>