Add leads to a campaign

The Add leads to a campaign endpoint adds new leads to the specified Dialer campaign.

Requirements: Base URL, Authentication, Error codes

Scope: campaigns.manage

What this does

When you send an Add leads request with a campaign ID,

Voiso

imports the leads into the campaign and returns an import result showing which leads were created, rejected, or already existed in the campaign.

Endpoint


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

Path parameters

campaign_id
The unique identifier of the campaign.

Request body

The request body is a JSON array of lead objects.

Required fields for each lead:

phone_number
The phone number of the lead.

Optional fields for each lead:

name
The display name of the lead.
source
Information about the external system that provided the lead.
priority
The lead priority. Lower values indicate higher priority. Range is 1 to 1000.
active
Indicates whether the lead should be called in this campaign.
context_headers
Custom SIP headers sent by
Voiso
during dialer calls to provide lead context to virtual agents.

Related endpoints

Get a campaign ID: Get list of campaigns
Verify the campaign exists: Get campaign

Example request

curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/3/leads" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "phone_number": "15551234567",
      "name": "John Doe",
      "priority": 10,
      "active": true,
      "source": {
        "system": "my_crm",
        "url": "https://example.com/leads/123"
      },
      "context_headers": {
        "X-Call-Context": "discount_promo_code",
        "X-Client-Order-Id": "1234"
      }
    },
    {
      "phone_number": "15557654321",
      "active": false
    }
  ]'

Response

If successful, the API returns a leads_import object.

{
  "leads_import": {
    "created": ["15551234567"],
    "rejected": ["15557654321"],
    "duplicates": ["15559876543"]
  }
}

Notes

created, rejected, and duplicates contain the phone numbers from your request.
context_headers keys must start with X- and may include only letters, numbers, and these characters: - _ . ! ~ * +.

Troubleshooting

409 Conflict

Returned when the request conflicts with the current state of the campaign.

422 Unprocessable Entity

Common causes:

A lead is missing phone_number.
A value is not valid, for example priority outside 1 to 1000.
context_headers contains an invalid header name.

429 Too many requests

Returned if requests are rate limited.