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,

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.