Lead lists

A lead list decides who a campaign calls. Every campaign has its own list, whose ID is the lead_list_id in the response when you create the campaign. You fill the list from any combination of these sources:

You change a list with PATCH /list/{lead_list_id}, and the response is the updated list. Set up the list before you launch the campaign: the campaign loads its leads from the list at launch.

Audiences

An audience adds every lead that matches a query:

PATCH /list/{lead_list_id}
{ "action": "set_audience", "query": { "field": "custom.campaign_tag", "op": "=", "value": "spring-promo" } }

While the campaign runs, new leads that match are added to it automatically. Sending set_audience again replaces the query, and { "action": "remove_audience" } removes it. See Audience queries for how to write a query.

Snapshots

A snapshot adds the leads that match a query when you send the request. Leads you create later are not added, even if they match, so create your leads first:

PATCH /list/{lead_list_id}
{ "action": "add_snapshot", "query": { "field": "custom.campaign_tag", "op": "=", "value": "spring-promo" } }

The leads are added in the background. Before you launch, call GET /static_list/{static_list_id}, using the ID in the list's static_list_ids, until its state changes from importing to active. A state of error means the snapshot failed. You can't start another snapshot on the list while one is importing.

Another add_snapshot adds the leads that match its query to the ones already there. refresh_snapshot, sent with a query, replaces them instead, and { "action": "clear_snapshot" } removes them.

Specific leads

To add leads you choose, send their ids, up to 1,000 per request:

PATCH /list/{lead_list_id}
{ "action": "add_leads", "lead_ids": ["<lead id>", "<lead id>"] }

Every ID must belong to one of your leads, or the whole request fails. remove_leads with lead_ids removes leads, and { "action": "clear_manual" } removes every lead added this way.

CSV files

Adding a CSV file takes three steps: upload the file, import its rows as leads, and attach it to the list. To load many leads at once, this is faster than creating them one at a time, which Dialpad's rate limits slow down.

Upload the file

Send the file as multipart form data in a file field, with an optional name (the file name by default). Set the file's content type to text/csv, or to application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for an Excel .xlsx file. Some clients, including curl, otherwise send a generic type, and the upload fails.

curl -X POST https://dialpad.com/api/v2/powerdialer/csv \
  -H "Authorization: Bearer $DIALPAD_API_KEY" \
  -F "[email protected];type=text/csv" \
  -F "name=Spring promo"

The file needs a header row and at least one row of data, and the first row of data must include a phone number. The response is the uploaded file, with its id and the header names in columns.

Import the rows

Map the file's columns to lead fields and start the import in one request:

PATCH /csv/{csv_id}
{
  "action": "import",
  "lead_mapping": { "Phone": "primary_phone", "First": "first_name", "Last": "last_name", "Email": "primary_email" },
  "custom_mapping": { "Tag": "campaign_tag" }
}

• lead_mapping maps column names to lead fields, and must include primary_phone, first_name and last_name. If you leave it out, PowerDialer tries to match columns to fields by name.
• custom_mapping maps column names to custom fields, which audience queries can match as custom.<name>.
• Columns you don't map aren't imported.

The import runs in the background. Call GET /csv/{csv_id} until its state changes from active to complete, or to error if the import failed. import_results then counts the leads created and updated. A row whose phone number matches one of your leads updates that lead instead of creating a new one.

Attach the file

PATCH /list/{lead_list_id}
{ "csv_ids": ["<csv id>"] }

csv_ids replaces the list's files, so include every file the list should call.

Using one list in several campaigns

A campaign's own list belongs to that campaign. To call the same leads from several campaigns, create a shared list:

POST /list
{ "name": "Spring promo leads" }

Fill it the same way as above, using its id in place of lead_list_id. Then set "shared_list": "<list id>" when you create each campaign, or update the campaign before you launch it. A campaign with a shared list calls that list instead of its own, and you can't change its shared list after launch.