Skip to Content
CallMitraDocs
API referenceLeads

Create a lead

Creates one lead and optionally adds it to campaigns. The phone is stored in E.164 form (a 10-digit number gets `+91`, as in a CSV upload); a number that cannot be read is refused with `invalid_phone_number`. The number is not checked for duplicates. Values that could not be saved as sent (an unknown status, a mistyped field) come back in `warnings`.

POST
/api/v1/leads/

Creates one lead and optionally adds it to campaigns. The phone is stored in E.164 form (a 10-digit number gets +91, as in a CSV upload); a number that cannot be read is refused with invalid_phone_number. The number is not checked for duplicates. Values that could not be saved as sent (an unknown status, a mistyped field) come back in warnings.

Authorization

headerX-API-Key<token>

Create in the console: Settings → API & webhooks.

Header Parameters

Idempotency-Key?string

Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice.

Lengthlength <= 255

Request Body

application/json
  1. body

A new lead. Every field is optional; send at least a phone number to call it.

attributes?

Profile facts, for example {"city": "Pune"}. Typed by your lead fields.

campaignIds?array<string>

Add the lead to these campaigns.

company?Company

Company name.

Default""
email?Email

Email address.

Default""
leadSourceId?Leadsourceid

ID of an existing lead source.

Default""
name?Name

Full name.

Default""
notes?Notes

Saved as the lead's first note.

Default""
phone?Phone

Phone number, saved in E.164 form: +919876543210, 9876543210 and 098765 43210 all save as +919876543210 (a number without a country code is taken as Indian). A value that is not a phone number returns 422 invalid_phone_number.

Default""
source?Source

Free-text source label, for example website.

Default""
status?Status

Pipeline status key. An unknown key saves as new with a warning.

Default"new"
title?|

Job title.

Default""

Response Body

OK

application/json
  1. response

The lead after the change.

lead*

The lead.

success?Success

Always true on a 2xx response.

Defaulttrue
warnings?array<>|

Values saved differently than sent (for example an unknown status).

[key: string]?any
Example Request
curl -X POST 'https://api.callmitra.ai/api/v1/leads/' \  -H 'Content-Type: application/json' \  -d '{  "attributes": {    "city": "Pune"  },  "company": "Rao Traders",  "email": "[email protected]",  "name": "Asha Rao",  "phone": "9876543210"}'
Example Response
{  "lead": {    "attributes": {      "city": "Pune"    },    "callAttempts": 0,    "callStatus": "not_called",    "campaignIds": [],    "campaignNames": [],    "company": "Rao Traders",    "createdAt": "2026-11-15T10:00:00+00:00",    "dncOptOut": false,    "email": "[email protected]",    "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d",    "name": "Asha Rao",    "phone": "+919876543210",    "source": "website",    "status": "new",    "tags": [],    "title": "Owner",    "updatedAt": "2026-11-15T10:00:00+00:00"  },  "success": true,  "warnings": []}