Create Lead

Creates a single lead in a campaign.

POST/api/v1/leads/create

Examples

Request

curl --request POST \
  --url 'https://api.vaanii.ai/api/v1/leads/create' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --data '{"campaign_id":"b7d7ec32-2be1-4ed2-a0d0-5f2b9ada8b67","first_name":"Ishaan","phone_e164":"+919546743365","country_code":"IN","custom_fields":{"loan_amount":497651,"city":"Bengaluru"}}'

Response

Possible HTTP status codes for this endpoint, with a representative response body for each. Select a status to preview it.

201 CreatedSuccessful response

{
  "id": "b43171f1-8735-4424-a21c-fbde6458d21f",
  "campaign_id": "b7d7ec32-2be1-4ed2-a0d0-5f2b9ada8b67",
  "first_name": "Ishaan",
  "phone_e164": "+919546743365",
  "status": "new",
  "custom_fields": {
    "loan_amount": 497651,
    "city": "Bengaluru"
  },
  "calls_count": 0,
  "updated_at": "2026-09-11T23:38:44+05:30",
  "next_scheduled_call": "2026-09-12T04:05:44+05:30"
}

Description

Verifies the campaign belongs to your company, normalizes the phone number, rejects duplicate active leads (same campaign + phone), and returns the created lead. If the campaign has auto-calling enabled, the lead is auto-enrolled for calling.

Request body (JSON)

Field	Type	Description
`campaign_id` `POST`	UUID	Campaign to add the lead to. Required.
`first_name` `POST`	string	Lead's first name. Required.
`phone_e164` `POST`	string	Phone number (country code inferred from `country_code`). Required.
`country_code` `POST`	string	Country code. Optional. Default: `IN`.
`custom_fields` `POST`	object	Extra campaign variables. Optional.

Errors

Status	Detail
`400`	Campaign not found or not in your company.
`400`	Invalid phone number format.
`400`	Lead with this phone already exists for this campaign.
`400`	Invalid `first_name` after preprocessing.