The Update campaign leads endpoint updates existing leads in the specified Dialer campaign.

Requirements: Base URL, Authentication, Error codes

Scope: campaigns.manage

What this does

When you send an Update campaign leads request with a campaign ID, Voiso updates the matching leads in that campaign and returns a result showing which leads were updated, rejected, or not found.

Endpoint


PATCH /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.
- source.system
  External system that provided the lead.
- source.url
  URL of the lead in the external system.
priority
The lead’s 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
Add new leads (instead of updating existing ones): Add leads to a campaign

Example request

Update a lead’s name, priority, and active status:

curl -X PATCH "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": 5,
      "active": true,
      "source": {
        "system": "my_crm",
        "url": "https://example.com/leads/123"
      },
      "context_headers": {
        "X-Client-Order-Id": "1234",
        "X-Call-Context": "discount_promo_code"
      }
    }
  ]'

Response

If successful, the API returns a leads_update object.

{
  "leads_update": {
    "updated": ["15551234567"],
    "rejected": ["15557654321"],
    "not_found": ["15559876543"]
  }
}

Notes

Lead matching is based on phone_number. If a phone number is not present in the campaign, it will appear in not_found.
updated, rejected, and not_found contain 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 or value.

429 Too many requests

Returned if requests are rate limited.