Audience queries

An audience query selects leads by their fields. PowerDialer uses these queries to decide which leads a dynamic campaign calls; see Creating a dynamic campaign. A query only ever matches active leads.

Conditions

A condition compares one lead field with a value:

{ "field": "primary_address.region", "op": "=", "value": "CA" }

field: the lead field to check (see Fields)
op: the operator (see Operators)
value: a string or a number. Leave it out for !! and ~~.

Operators

Operator	Matches leads where the field...
`=`	equals the value
`!=`	does not equal the value
`<` `<=` `>` `>=`	is less than, at most, greater than, or at least the value
`^=`	starts with the value
`$=`	ends with the value
`~=`	contains a match for the value as a regular expression (RE2 syntax)
`!!`	is empty
`~~`	is not empty

Text comparisons ignore case.

Combining conditions

To combine conditions, put them in a group with a combiner of "AND" or "OR". Groups can contain other groups.

This query matches leads with a Gmail address who are in California or Texas:

{
  "combiner": "AND",
  "conditions": [
    { "field": "primary_email", "op": "$=", "value": "@gmail.com" },
    {
      "combiner": "OR",
      "conditions": [
        { "field": "primary_address.region", "op": "=", "value": "CA" },
        { "field": "primary_address.region", "op": "=", "value": "TX" }
      ]
    }
  ]
}

Fields

Fields	Notes
`first_name`, `last_name`, `job_title`, `industry`, `role`, `department`
`primary_email`, `secondary_email`
`primary_phone`, `secondary_phone`, `mobile_phone`, `home_phone`	Phone numbers in E.164 format, such as `+14155550123`
`primary_address.name`, `.line1`, `.line2`, `.city`, `.region`, `.postal_code`, `.country`
`external_id`	Your own ID for the lead, such as a CRM contact ID
`lead_source`	How the lead was created, such as `api` or `csv`
`lang`, `timezone`
`custom.<name>`	Any key you set in a lead's `custom` object. There is no need to register custom fields first.

Using a query

You can set a query directly on a campaign's lead list, which is the simplest way and the one the guide uses:

PATCH /list/{lead_list_id}
{ "action": "set_audience", "query": { ... } }

To reuse the same query across several campaigns, save it once as an audience with POST /audience (a name and a query), then attach it to each list with PATCH /list/{lead_list_id} and "audience_ids": [...]. Note that audience_ids replaces the list's existing audiences rather than adding to them. A campaign can use up to 20 audiences.

A running campaign keeps the query it had when it launched. Changing the audience afterwards does not affect that campaign.