Discovery
Turn a description into filters
POST
Turns plain English into audience filters, a summary and matching topics. Free. Nothing is built: create an audience from the filters to get a count.
bearerAuthheader
AuthorizationBearer <API key>Create a key in the app under Developers. Keys start with dcd_live_.
application/json- body
prompt*stringPlain-English description of the people you want, such as 'homeowners in Texas shopping for solar panels'.
Length
1 <= length <= 2000Success.
application/json- response
Free. Nothing is built or charged until you create an audience from the filters.
type*stringAudience type chosen. Same as filters.type.
Value in
"b2c""b2b""people"filters*The filters we built from your description. Review them, then create an audience with them.
summary*stringOne or two sentences saying what the filters will find.
topic_matches*array<>The intent topics we matched to your description.
request_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/describe' \ -H 'Authorization: Bearer dcd_live_your_key' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "Homeowners in Texas shopping for solar panels"}'Example Response
{ "type": "b2c", "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" } ] }, "summary": "string", "topic_matches": [ { "id": "string", "name": "string", "category": "string", "subcategory": "string" } ], "request_id": "string"}