Creating a dynamic campaign

This guide creates a PowerDialer campaign that calls the leads matching a query, then keeps adding new leads that match as you create them. It takes four requests.

Before you start

You need:

an API key; see PowerDialer API
the ID of the call center the campaign will dial through. List your call centers with the Call Centers API.

Every request below goes to https://dialpad.com/api/v2/powerdialer and sends your API key as a bearer token.

1. Create the campaign

curl -X POST https://dialpad.com/api/v2/powerdialer/campaign \
  -H "Authorization: Bearer $DIALPAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": 1234567890,
    "name": "Spring promo follow-ups",
    "caller_id": "+14155550100",
    "auto_create": true,
    "set_timegate": true,
    "date_scheduled_end": "2026-12-31T23:59:59Z"
  }'

group_id (required): your call center ID.
auto_create: adds a default call step that dials each lead once.
set_timegate: limits calling to Monday to Friday, 8am to 9pm, in each lead's local time based on their phone number. Without it, the campaign has no calling-hours limit.
date_scheduled_end: when the campaign stops. Always set one. A campaign without an end date keeps running until someone stops it.

The response is the new campaign. Save its id and lead_list_id for the next steps:

{
  "id": "6f1c2a4e-1b7d-4c3e-9a51-2d8e0f6b7c90",
  "lead_list_id": "b2d94e17-5c08-4a6f-8e3b-71c0a9f25d4e",
  "name": "Spring promo follow-ups",
  "state": "pending"
}

2. Choose who to call

Set a query on the campaign's lead list. This one selects every lead whose custom field campaign_tag is spring-promo:

curl -X PATCH https://dialpad.com/api/v2/powerdialer/list/$LEAD_LIST_ID \
  -H "Authorization: Bearer $DIALPAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_audience",
    "query": { "field": "custom.campaign_tag", "op": "=", "value": "spring-promo" }
  }'

Queries can match on other fields and combine several conditions. See Audience queries.

Set the query before you launch: a campaign becomes dynamic at launch only if its list already has a query.

3. Launch the campaign

curl -X PATCH https://dialpad.com/api/v2/powerdialer/campaign/$CAMPAIGN_ID \
  -H "Authorization: Bearer $DIALPAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "launch" }'

Launching takes a little time, so the response shows the campaign in the launching state. Check on it with GET /campaign/{campaign_id} until state changes to:

active: the campaign is dialing
scheduled: it will start at its date_scheduled_start
error: the launch failed

Leads that already match the query when you launch are added straight away. A dynamic campaign can launch with no matching leads yet; it waits for them.

4. Add leads

curl -X POST https://dialpad.com/api/v2/powerdialer/lead \
  -H "Authorization: Bearer $DIALPAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone_number": "+14155550123",
    "external_id": "crm-contact-8812",
    "custom": { "campaign_tag": "spring-promo" }
  }'

phone_number (required): if one of your leads already has this primary phone number, that lead is updated instead of a new one being created.
first_name and last_name: required for a new lead.
external_id: optional; your own ID for the lead, such as its CRM contact ID.
custom: your own fields. These are the values audience queries match on.

While the campaign is active, new leads that match its query are added to it automatically, usually within a minute.

Managing the campaign

The campaign now appears in PowerDialer alongside your other campaigns. To pause it, send { "action": "pause" } to PATCH /campaign/{campaign_id}. To end it before its end date, send { "action": "stop" }; this is what happens automatically when the end date passes.