Calls

Start a click-to-call

POST /v1/calls

Scope

calls:originate

Tier

Tier 2 (reaches or unlocks real people)

Data

Personal data

Idempotency

Idempotency-Key: required

Connects one of your agents with a customer. DialerBee first checks that the agent (named by extension or by sign-in email) belongs to the account and is signed in and ready (409 agent_unavailable otherwise, and nothing is dialled), then dials the customer from one of the account's own verified caller IDs (or the caller_id you name, which must be one of the account's verified numbers: any other number is 422 dial_refused with caller_id_not_registered and nothing is dialled) and joins the agent the moment the customer answers. Every compliance check runs before the dial, exactly as for a call started in the console: a refusal is 422 dial_refused (or on_dnc / blocked_country, or 402 insufficient_balance) and nothing is dialled. call_id names the call record when it can be matched at once; otherwise it is null and the call still appears in GET /v1/calls and in the call webhooks. Retry only with the same Idempotency-Key: a new key places a new call.

The agent is held for this call before the customer is dialled (shown as ringing, so the dialler, the queues and a second click-to-call do not give the agent another call meanwhile) and released at once when the call is refused. A request for an agent who is already held answers 409 agent_unavailable.

TIER 2: needs the scope calls:originate, the account switch tier2_calls_originate_enabled and a key made by the account's guided sending setup (IP allow-list, daily cap, per-minute cap). The account's own caps, estimated-spend limit, minimum balance and "stop all sending" switch apply, and the call is ended after 30 minutes by default (set by the platform) (429 daily_cap_reached / rate_limit_exceeded / spend_cap_reached, 402 insufficient_balance, 403 sending_suspended); a new self-service account answers 403 outbound_not_approved until DialerBee approves its outbound calling.

Parameters

Request body

Who to call and which agent takes the call.

JSON: CallCreateRequest

Response

201: The customer is being dialled; the agent joins on answer.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/calls" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "to": "+12125550101",
  "agent_extension": "3901",
  "campaign_id": "cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
  "lead_id": "lead_0f8fad5b-d9cb-469f-a165-70867728950e"
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.calls.create(
    to="+12125550101",
    agent_extension="3901",
    campaign_id="cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
    lead_id="lead_0f8fad5b-d9cb-469f-a165-70867728950e",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

201

{
  "call_id": "call_0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "dialing",
  "to": "+12125550101",
  "agent_extension": "3901",
  "caller_id": null,
  "campaign_id": "cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
  "lead_id": "lead_0f8fad5b-d9cb-469f-a165-70867728950e",
  "recording": true,
  "created_at": "2026-09-29T12:00:00Z"
}

Error examples

409 agent_unavailable

{
  "type": "https://docs.dialerbee.com/errors/agent-unavailable",
  "title": "Agent not available",
  "status": 409,
  "detail": "The agent is not signed in, is on a call, in wrap-up or on a break, or is already held for another call, so nothing was dialled.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "agent_unavailable",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

422 dial_refused

{
  "type": "https://docs.dialerbee.com/errors/dial-refused",
  "title": "Call refused by a compliance check",
  "status": 422,
  "detail": "A compliance check refused the call (for example calling hours, the caller ID is not one of the account's registered numbers, or the account cannot place calls now), so nothing was dialled.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "dial_refused",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

422 on_dnc

{
  "type": "https://docs.dialerbee.com/errors/on-dnc",
  "title": "Destination is on DNC",
  "status": 422,
  "detail": "The number is on the account's Do-Not-Call list, so this action is refused.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "on_dnc",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

CallCreateRequest

Name the agent by exactly one of agent_extension or agent_email.

CallStarted