---
title: "Add leads to a campaign"
method: POST
path: "/api/v4/campaigns/{campaign_id}/leads"
tags: ["Campaigns"]
---

# Add leads to a campaign

`POST /api/v4/campaigns/{campaign_id}/leads`

## Request

- Base URL: `https://{cluster_id}.voiso.com`
- URL: `https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/leads`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/voiso/apis/voiso-api/docs/api/v4/campaigns/:campaign_id/leads/post.ts> (a function with typed inputs; its response is checked against the schema)

Adds leads to the specified campaign.

## Path parameters

- `campaign_id` integer, required

## Request body

- Lead[]
  - `phone_number` string, phone, required: The phone number of the lead.
  - `name` string: The display name of the lead.
  - `source` object: Information about the external system that provided the lead, such as a CRM.
    - `system` string: External system that provided the lead.
    - `url` string, uri: URL of the lead in the external system.
  - `priority` integer: The lead's priority for calling purposes. Lower values indicate higher priority. Leads without a priority are called last.
  - `active` boolean: Indicates whether the lead should be called in this campaign.
  - `context_headers` object: Custom SIP headers sent by {BRAND} during dialer calls to provide lead context to virtual agents. Each key represents a SIP header name (must start with "X-" and contain only a-z, A-Z, 0-9, -, _, ., !, ~, *, +), and each value represents the corresponding header value.

## Response `200`

OK

- object
  - `leads_import` LeadsImport: Result of importing leads into a campaign.
    - `created` string[]: Phone numbers of leads that were successfully created.
    - `rejected` string[]: Phone numbers of leads that were rejected.
    - `duplicates` string[]: Phone numbers of leads that were already present in the campaign.
    - `campaign_leads` CampaignLeadShort[]: Campaign leads created by this request, one per entry in `created`, in the same order.
      - `id` integer: The unique identifier of the campaign lead. The same value is returned as `campaign_lead_id` in the CDR API and the dialer call event webhooks.
      - `phone_number` string, phone: The phone number of the lead, as sent in the request.

## Other responses

- `409`: Conflict
- `422`: Unprocessable Entity
- `429`: Too many requests

## Changes

- **2026-11-03** `5a6ea146bd21`: 1 info
  - added the optional property `leads_import/campaign_leads` to the response with the `200` status

[Operation history](https://skmtc.dev/voiso/apis/voiso-api/changes/api/v4/campaigns/:campaign_id/leads/post.md)

---

[API](https://skmtc.dev/voiso/apis/voiso-api.md) - [All operations](https://skmtc.dev/voiso/apis/voiso-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voiso/apis/voiso-api/revisions/5a6ea146bd21?raw)