Getting started with the DICE API

Create an API key, send your first lead and read it back. The public API is REST over HTTPS with JSON bodies.

1. Create a key

In the portal, open Developers → API keys → New key. Pick only the scopes you need. The full key is shown once; store it in your secret manager.

dice_live_… keys act on real data. New leads go through the full pipeline: first reply, scoring and the owner alert.
dice_test_… sandbox keys create sandbox records only, never message anyone and only see sandbox data. Use them while you build.

Agency keys can act on one client at a time with the Dice-Business: <business id> header. GET /api/v1/businesses lists the clients.

2. Send a lead

curl https://diceautomation.com/api/v1/leads \
  -H "Authorization: Bearer $DICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-4711" \
  -d '{"first_name":"Ada","email":"[email protected]","message":"Furnace repair","consent":{"contact":true}}'

The answer holds an intake_id. Poll GET /api/v1/intakes/{intake_id} until status is completed; it then carries the lead_id. Sandbox keys return the lead at once.

3. Read it back

GET /api/v1/leads/{id} returns the lead with its score and status. Lists take limit (up to 100) and cursor: pass next_cursor from one page to get the next.

Scopes

Scope	Allows
`leads:read` / `leads:write`	Read leads; create, update and change the status of leads
`conversations:read`	Read conversations and messages (internal notes are never returned)
`appointments:read` / `appointments:write`	Read appointments and free times; book and cancel
`knowledge:read` / `knowledge:write`	Read and add knowledge sources and Q&A answers
`webhooks:manage`	Manage webhook endpoints and REST-hook subscriptions
`usage:read`	Read usage for the current period

Limits and errors

Each key has a per-minute limit (120 by default, 60 for sandbox keys). Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 carries Retry-After.
Send an Idempotency-Key on POST requests. Repeating a request with the same key within 24 hours returns the first answer instead of creating a second record.
Errors use one envelope: { "error": { "code": "…", "message": "…", "requestId": "…" } }. Quote the requestId when you contact support.

Next: webhooks, the TypeScript SDK and the API reference.