DialerBee APIv1 · 1.0.0-rc6

Getting started

This page is the short version. Each section links to the full page.

Base URL

Every request goes to this address, followed by the path from the API reference:

https://app.dialerbee.com/api

For example, GET /v1/me is https://app.dialerbee.com/api/v1/me. Use HTTPS only. The API is server to server: call it from your own server, not from a web browser.

Your key

DialerBee switches API access on for your account. Then an admin of your account opens Settings → API clients in the DialerBee console, creates an API client for your integration and creates a key for it. The key is shown once, so store it in your secret store straight away.

A key looks like dbk_live_<credential id>_<secret>. Send it in the Authorization header and nowhere else:

Authorization: Bearer dbk_live_<credential id>_<secret>

A key in the URL or in the body is refused, and you must then treat that key as exposed: revoke it and create a new one. If your API client has an IP list, requests from any other address are refused. More on the Authentication and API keys pages.

Your first requests

Check the key. GET /v1/me works with any active key and shows the scopes your API client holds:

export DIALERBEE_API_KEY='dbk_live_...'   # from your secret store

curl -sS https://app.dialerbee.com/api/v1/me \
  -H "Authorization: Bearer $DIALERBEE_API_KEY"

List your latest calls (needs the calls:read scope):

curl -sS "https://app.dialerbee.com/api/v1/calls?limit=5" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY"

List your campaigns (needs campaigns:read):

curl -sS "https://app.dialerbee.com/api/v1/campaigns?limit=20" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY"

Lists come back one page at a time. When there is more, the answer's page.next_cursor is set; send it back as ?cursor=... to get the next page. See Pagination.

Every write that changes data needs an Idempotency-Key header with your own unique value, so a retry never does the same thing twice. See Idempotency.

Limits

Using the API is free. Each key, API client, account and source address has a request rate with a short burst on top. When you go over a limit you get 429 with a Retry-After header in seconds: wait at least that long, then retry. The numbers are on the Rate limits page.

Errors

Every error has the same JSON shape, with a stable code you can program against and a request_id:

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}
Status What it usually means
400 The request is malformed, or a key was sent in the URL or body.
401 The key is missing, wrong, expired or revoked.
403 API access is off, the address is not allowed, or the API client lacks a scope.
404 No such object in your account, or no such route.
409 / 422 The request conflicts with the current state, or a field is invalid.
429 Too many requests: follow Retry-After.
5xx A problem on our side: retry later with the same Idempotency-Key.

When you contact support, send the request_id (it is also in the X-Request-ID response header). Every code has its own page: Errors.

What is not open yet

Click-to-call and SMS sending work once your account administrator switches them on in the guided sending setup. WhatsApp sending is not open yet, and the other Tier-2 actions answer an error that says so until your account's switch for them is on. Reading calls, campaigns, leads, reports, recordings and transcripts, importing leads into a campaign that is not running, adding numbers to Do-Not-Call and webhooks work as described.

Tools