Create an audience
Starts building an audience from filters or from a plain-English prompt. Free. Returns straight away with status 'building'. Poll GET /v1/audiences/{id} or subscribe to the audience.ready webhook.
Send an Idempotency-Key header so a retry never builds twice.
bearerAuthAuthorizationBearer <API key>Create a key in the app under Developers. Keys start with dcd_live_.
Idempotency-Key?stringUnique string for this request. Repeat the call with the same key within 24 hours and you get the original result, marked with the header Idempotent-Replayed: true, without being charged or building twice. Reusing a key with a different request is a 409. A request that failed can be retried with the same key.
1 <= length <= 255application/json- body
Start building an audience. Free. It returns straight away with status 'building'.
name?stringName for the audience. We pick one if you leave it out.
1 <= length <= 120filters?Exact filters to build from. Send this or prompt, not both.
prompt?stringPlain-English description to build from. We turn it into filters. Send this or filters, not both.
1 <= length <= 2000limit?integerBuild size. One build stages at most 500 leads for preview and reveal however many match (see match_count), so values above 500 count as 500. Leave out for 500.
1 <= value <= 1000000topic_labels?Display names for topic ids in filters, keyed by topic id, as returned by GET /v1/topics; up to 120 characters each. Only with filters, and only for topics in filters.topics. Used to label each lead's intent topic in this audience. Topics left out are labelled with their id.
Success.
application/json- response
A set of leads that match your filters. Previewing it is free. Revealing leads costs chips.
id*stringAudience id. Starts with aud_.
^aud_name*stringAudience name.
type*stringAudience type. 'b2c' is Consumers, 'b2b' is Businesses (both are built from intent topics). 'people' is a plain people search with no intent data.
"b2c""b2b""people"status*string'building' while we assemble it, 'ready' once leads can be previewed and revealed, 'failed' if the build failed.
"building""ready""failed"filters*What to look for. Pick a type, add topics for b2c and b2b, then narrow with the optional groups or with where[] clauses.
prompt*|The plain-English description it was built from, if any.
total_count*integerLeads the audience holds for preview and reveal: at most 500 from a build, plus any a watch run added. Zero until the audience is ready.
0 <= value <= 9007199254740991total_is_capped*booleanTrue when more leads match than the audience holds (it hit the build limit or the preview size); show total_count as N+, or show match_count.
match_count?|Every lead that matches the filters, counted when the audience was last built or watched. Often far more than total_count, which is what can be previewed and revealed. Null when unknown.
saved*booleanWhether the audience is saved in the app.
watch*|Watch schedule. Null when the audience is not watched.
next_run_at*|When the next watch run starts. Null when the audience is not watched.
last_run*|The most recent run.
created_at*stringWhen the audience was created.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$date-timerequest_id*stringId of the request that produced this response. A replayed idempotent response keeps the original id.
curl -X POST 'https://api.diced.si/v1/audiences' \ -H 'Authorization: Bearer dcd_live_your_key' \ -H 'Idempotency-Key: 9b2f6c1e-4d7a-4f0b-8e3a-1c5d2e7f9a04' \ -H 'Content-Type: application/json' \ -d '{ "name": "Texas solar", "filters": { "type": "b2c", "topics": [ "tp_4521" ], "location": { "states": [ "TX" ] }, "demographics": { "homeowner": true } }, "limit": 5000}'{ "id": "string", "name": "string", "type": "b2c", "status": "building", "filters": { "type": "b2c", "topics": [ "string" ], "intent": [ "high" ], "active_within_days": 1, "location": { "states": [ "AK" ], "zips": [ "string" ], "cities": [ "string" ] }, "demographics": { "gender": [ "male" ], "age": [ "18-24" ], "income": [ "<20k" ], "net_worth": [ "<0" ], "homeowner": true, "married": true, "children": true }, "job": { "titles": [ "string" ], "seniority": [ "c_suite" ], "departments": [ "administrative" ] }, "company": { "names": [ "string" ], "domains": [ "string" ], "industries": [ "string" ], "size": [ "1-10" ], "revenue": [ "<1m" ] }, "where": [ { "field": "active_date", "op": "eq", "value": "string", "value_to": "string" } ] }, "prompt": "string", "total_count": 0, "total_is_capped": true, "match_count": 0, "saved": true, "watch": { "interval": "day", "auto_reveal": false, "cap": 100 }, "next_run_at": "2019-08-24T14:15:22Z", "last_run": { "id": "string", "kind": "build", "status": "running", "total_count": 0, "new_count": 0, "revealed_count": 0, "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z" }, "created_at": "2019-08-24T14:15:22Z", "request_id": "string"}