Scopes
Every operation names the one scope it needs. An API client holds a set of scopes, granted by your
account admin in the console. A request whose client lacks the scope is refused with 403
insufficient_scope.
- A new API client has no scopes: its keys can call only
GET /v1/me. - Grant each integration only the scopes it uses. A reporting tool needs
calls:read, notleads:write. calls:read,recordings:read,transcripts:readandsummaries:readcover every call of the account, from every team, campaign and agent. There is no team-level restriction inv1.summaries:readlets a CRM sync AI summaries without access to full transcripts.- A Tier 2 scope is not enough on its own: the matching account switch must be on too. See Tiers.
| Scope | Allows | Tier | Operations |
|---|---|---|---|
| none | Any active key. | 1 | GET /v1/me |
leads:read | Read leads (contacts) of every campaign of the account, including their history. | 1 | GET /v1/leads, GET /v1/leads/{lead_id}, GET /v1/leads/{lead_id}/history |
leads:write | Import leads into a paused, draft or ready campaign through the platform's own validation (phone checks, duplicates, field rules, Do-Not-Call screen), add one lead to a paused, draft or ready campaign, and update a lead's name, email and custom fields. Never changes a phone number. Adding a lead to a running campaign, or asking for it to be dialled first, also needs calls:originate and the account's click-to-call switch, because the dialler then calls the person within seconds. | 1 | POST /v1/leads/import, POST /v1/leads, PATCH /v1/leads/{lead_id} |
campaigns:read | Read campaigns, their status and their progress counts. | 1 | GET /v1/campaigns, GET /v1/campaigns/{campaign_id}, GET /v1/campaigns/{campaign_id}/progress |
campaigns:pause | Pause a running campaign. Pausing only reduces contact. | 1 | POST /v1/campaigns/{campaign_id}/pause |
campaigns:resume | TIER 2. Resume a paused campaign: this starts real calls. Needs the account switch tier2_campaign_resume_enabled. | 2 | POST /v1/campaigns/{campaign_id}/resume |
calls:read | Read call records: all calls of the account, from every team, campaign and agent. There is no team-level restriction in v1. | 1 | GET /v1/calls, GET /v1/calls/{call_id} |
calls:originate | TIER 2. Make DialerBee call a person: start a click-to-call (DialerBee checks that the named agent is signed in and ready and holds the agent for this call, then dials the customer from one of the account's own verified caller IDs and connects the agent), and, together with leads:write, add a lead to a running campaign or ask for it to be dialled first. Every compliance check (Do-Not-Call, calling hours, consent, caller ID ownership, blocked countries, balance) still runs. Needs the account switch tier2_calls_originate_enabled and a key made by the guided sending setup (IP allow-list and caps). | 2 | POST /v1/calls |
recordings:read | Stream call recordings (all calls of the account). | 1 | GET /v1/calls/{call_id}/recording |
transcripts:read | Read call transcripts (all calls of the account). | 1 | GET /v1/calls/{call_id}/transcript |
summaries:read | Read the AI summary of a call, without access to the full transcript. | 1 | GET /v1/calls/{call_id}/summary |
webhooks:read | Read webhook endpoints, events and deliveries. | 1 | GET /v1/webhooks, GET /v1/webhooks/{webhook_id}, GET /v1/webhook-events, GET /v1/webhook-events/{event_id} |
webhooks:write | Create, change, delete and test webhook endpoints, rotate their secrets and replay events. | 1 | POST /v1/webhooks, PATCH /v1/webhooks/{webhook_id}, DELETE /v1/webhooks/{webhook_id}, POST /v1/webhooks/{webhook_id}/rotate-secret, POST /v1/webhooks/{webhook_id}/test, POST /v1/webhook-events/{event_id}/replay |
dnc:check | Check whether numbers are on the account's Do-Not-Call list. Answers only listed or not listed. | 1 | POST /v1/dnc/check |
dnc:add | Add a number to the account's Do-Not-Call list. Adding only reduces contact. | 1 | POST /v1/dnc |
consent:write | TIER 2. Record consent evidence for a number: this can make it callable. Needs the account switch tier2_consent_write_enabled. | 2 | POST /v1/consents |
callbacks:read | Read scheduled callbacks. | 1 | GET /v1/callbacks |
callbacks:cancel | Cancel a pending callback. Cancelling only removes a planned call. | 1 | POST /v1/callbacks/{callback_id}/cancel |
callbacks:write | TIER 2. Schedule or move a callback: this schedules a real call. Needs the account switch tier2_callback_write_enabled. | 2 | POST /v1/callbacks, POST /v1/callbacks/{callback_id}/reschedule |
appointments:read | Read appointments. | 1 | GET /v1/appointments, GET /v1/appointments/{appointment_id} |
appointments:write | TIER 2. Book, reschedule or cancel an appointment: the account's confirmation service may text the customer. Needs the account switch tier2_appointment_write_enabled. | 2 | POST /v1/appointments, POST /v1/appointments/{appointment_id}/reschedule, POST /v1/appointments/{appointment_id}/cancel |
sms:read | Read SMS delivery reports and SMS usage counters. | 1 | GET /v1/sms/delivery-reports, GET /v1/sms/usage |
messages:send | TIER 2. Send an SMS from the account's own sender name, after the same compliance checks as the console (Do-Not-Call, calling hours, consent, blocked countries, balance). Needs the account switch tier2_sms_send_enabled and a key made by the guided sending setup (IP allow-list and caps); a repeated client_reference is refused, so a retry never sends twice. | 2 | POST /v1/sms |
whatsapp:send | Send WhatsApp messages (text or an approved template) from the account's own WhatsApp number. A repeated client_reference is refused, so a retry never sends twice. Not available yet; sending answers 403 tier_not_enabled for every account until DialerBee announces it. | 1 | POST /v1/whatsapp/messages |
reports:read | Read aggregated reports (disposition counts). | 1 | GET /v1/reports/dispositions |