Quickstart

You need a Diced account. New workspaces get 25 free chips once the email is verified, which is enough to finish this page.

0. Create an API keyCopy Anchor Link

In the app, open Developers → API keys and create a key. It starts with dcd_live_ and is shown once, so copy it somewhere safe. Then put it in your shell:

export DICED_API_KEY="dcd_live_..."

Every request sends it as a bearer token: Authorization: Bearer dcd_live_....

1. Check the keyCopy Anchor Link

curl https://api.diced.si/v1/me \
  -H "Authorization: Bearer $DICED_API_KEY"

You get your workspace, the key's name and prefix, and your chip balance.

2. Describe who you wantCopy Anchor Link

POST /v1/describe turns plain English into filters and matching intent topics. It's free, and nothing is built yet.

curl https://api.diced.si/v1/describe \
  -H "Authorization: Bearer $DICED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Homeowners in Texas shopping for solar panels"}'

{
  "type": "b2c",
  "filters": {
    "type": "b2c",
    "topics": ["tp_4521"],
    "location": { "states": ["TX"] },
    "demographics": { "homeowner": true }
  },
  "summary": "Texas homeowners researching solar panels in the last 14 days.",
  "topic_matches": [{ "id": "tp_4521", "name": "Solar Panels", "category": "Home", "subcategory": null }],
  "request_id": "req_8fK2..."
}

Check the filters, edit them if you like, then build. The full list of fields is in the filters reference.

3. Build the audienceCopy Anchor Link

POST /v1/audiences starts a build and answers straight away with status: "building". It's free. Send an Idempotency-Key so a retry never builds twice. You can also send { "prompt": "..." } instead of filters to describe and build in one call.

curl https://api.diced.si/v1/audiences \
  -H "Authorization: Bearer $DICED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Texas solar",
    "filters": {
      "type": "b2c",
      "topics": ["tp_4521"],
      "location": { "states": ["TX"] },
      "demographics": { "homeowner": true }
    }
  }'

4. Wait for it, then previewCopy Anchor Link

Poll GET /v1/audiences/{id} every few seconds until status is ready (or failed). Builds usually take under a minute. If you'd rather not poll, subscribe to the audience.ready webhook. Then page through the free preview: names, city, job, company and intent, with contact details hidden.

curl https://api.diced.si/v1/audiences/aud_123 \
  -H "Authorization: Bearer $DICED_API_KEY"

# once it's ready: the free, masked preview
curl "https://api.diced.si/v1/audiences/aud_123/leads?limit=25" \
  -H "Authorization: Bearer $DICED_API_KEY"

5. Reveal leadsCopy Anchor Link

POST /v1/audiences/{id}/reveal spends 1 chip per lead you haven't revealed before and returns the leads in full. max_chips is required: if the Reveal would cost more, nothing is revealed or charged and you get max_chips_exceeded. Reuse the same Idempotency-Key when you retry, and you get the first answer back without paying twice.

curl https://api.diced.si/v1/audiences/aud_123/reveal \
  -H "Authorization: Bearer $DICED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reveal-aud_123-first-10" \
  -d '{"count": 10, "max_chips": 10}'

count reveals the next leads you haven't unlocked, in audience order. Send lead_ids instead to pick leads from the preview. If the audience holds fewer leads than you asked for, you're charged only for the ones that exist. Revealed leads stay in your workspace: list them any time with GET /v1/leads.

NextCopy Anchor Link

• Watch the audience to get new leads every day, week or month.
• Set up webhooks instead of polling.
• Connect Claude or ChatGPT and do all of this in a chat.
• Handle errors and rate limits.