Using Call

The Call API and Webhooks for Developers: Keys, Scopes, Events

A practical tour of the Call REST API: API keys and scopes, rate limits, error handling, signed webhooks and the Developers page where you manage endpoints.

Call editorial team · Published · 6 min read

Sooner or later a phone system has to talk to something else: a CRM that should show a call as it ends, a billing tool that wants to know who rang, a script that places a call when a form is submitted. Call has a REST API and outbound webhooks for exactly this. This guide explains how the pieces fit, what to ask for before you write code, and the mistakes that most often cost a developer an afternoon.

A developer reviewing an integration on a laptop beside a desk phone
Illustrative image

If your goal is simply to move contacts in bulk, read Importing Contacts into a Phone-Team CRM first; an import is often easier than an integration.

Where to start: the reference and the Developers page

There are two places to know. The API reference lives under Settings, and also in the Resources menu of the home page. It can be read without signing in, which is handy when you are scoping work for a client. The Developers page, also under Settings, is for your own workspace: it shows your organisation and agent identifiers, your webhook endpoints and a read-only list of your keys.

What each place gives you

  • Start hereBase URL and conventions, authentication with a scopes table, and errors with status codes.
  • EndpointsEach endpoint card lists its scope, parameters, request body, response and errors, with ready-to-copy requests in curl, JavaScript and Python.
  • SearchPress / to jump to Search endpoints and filter by method, path, scope or summary.
  • OpenAPI JSONDownloads the whole specification as a single file for your own tools.
  • Agent ID / APIYour organisation ID and slug, the API mode (Sandbox or Live) and the ID of the AI agent you pick, each with a Copy button.
  • WebhooksYour endpoints, the events each one receives, the last HTTP status and any failed deliveries.

Read the sections on rate limits and outbound webhooks before you go live, not after. They describe behaviour that is easy to miss in a quick test.

API keys and scopes

Every request carries a key in an Authorization header as a bearer token. Keys are not created in the app: the operator of your workspace issues them and tells you which scopes they carry. The full key is shown once at the moment it is issued, and afterwards only its first characters appear, so store it in your own secret store straight away.

ScopeWhat it allows
readRead contacts, calls, queues, team members, reports and the do-not-call list.
writeCreate and update contacts, record call outcomes, add numbers to the do-not-call list.
callsPlace and end calls.
adminManage webhooks; may also call every other endpoint.

Ask for the smallest set that does the job. A reporting script needs read and nothing else; a click-to-call button needs calls. If a request returns a 403 with the code insufficient_scope, the key lacks the scope shown on that endpoint's card.

Sandbox and live

Keys can be issued for a sandbox, which uses a simulator and places no real calls, or for live use. Treat the prefix of a key as a label only: a test-labelled key works on the same data and the same phone connection as a live one, so do not rely on the prefix to keep experiments away from real customers. Use the API mode shown on the Developers page to know where you stand.

Placing calls through the API

The public endpoints cover the basics: a health check, listing calls, reading one call, placing a call, hanging up, managing webhooks and chatting with an AI agent. An outbound call placed through the API passes the same compliance check as a call placed from the desk, so a number on the do-not-call list or outside permitted calling hours is refused, exactly as it would be for an agent. Build your code to handle that refusal as a normal outcome, not a bug.

This matters for design. Do not write a loop that retries a refused call until it works. Read the reason, log it, and move on. For the rules behind those refusals see Calling-Hours Guard in Call and The Do-Not-Call List in Call.

Rate limits and errors

Each key has its own limit of requests per minute, set when the key is issued; the default is 120. When a key uses up the minute, the API answers 429 with the code rate_limited and tells you how long to wait in the X-RateLimit-Reset header. Wait that long, then continue. A polite client slows itself down before it hits the wall.

Handling a failed request

  1. Read the statusIs it a client error you can fix, or a server error worth retrying?
  2. Read the codeBranch on the code, never on the message text.
  3. Back offFor 429, wait for the reset header; for server errors, retry a few times with growing delays.
  4. Log the detailKeep the endpoint, the code and the time so support can trace it.
  5. Stop on refusalsA compliance refusal is a decision, not a glitch; do not loop on it.

Webhooks: receiving events

Instead of asking the API again and again whether something happened, let Call tell you. On the Developers page, press Add endpoint, enter a public https address, and tick the events you want; ticking none means all events. The signing secret is displayed once, when the endpoint is added. Copy it then. If it is lost, delete the endpoint and add it again to get a new one.

Each delivery is signed. The signature header holds an HMAC-SHA256 of the timestamp and the body joined by a full stop, computed with your signing secret, and a separate header carries the timestamp. Recompute it on your side and compare before you trust the payload. The API reference includes sample code for this in Node.js and Python, and rejecting old timestamps protects you against replayed requests.

A good and a poor webhook receiver

GoodPoor
SignatureVerified on every requestTrusted without checking
Reply2xx within seconds, work queued for laterSlow processing before replying
DuplicatesSafe to receive the same event twiceCreates two records
FailuresAlerts when deliveries failSilent until someone notices

Your endpoint must answer with a 2xx status within 10 seconds. A failed delivery is tried again, up to six attempts in all, and an endpoint that fails 50 times in a row is switched off. Each row on the Developers page shows the last HTTP status and how many deliveries failed, and Send test fires one signed test event so you can see what your server answers.

A go-live checklist

Before you switch an integration on

  • You know which scopes the key has, and it has no more than needed
  • The key is stored in a secret store, not in source code
  • Webhook signatures are verified and old timestamps rejected
  • The receiver answers quickly and handles duplicate events
  • Rate-limit and refusal responses are handled without tight retry loops
  • You tested in sandbox mode and pressed Send test on the endpoint
  • Someone is named to receive an alert if deliveries start failing

Doing it in Call

In Call, open Settings, then API reference to study the endpoints, and Settings, then Developers to copy your organisation ID, check your keys and add a webhook. Owners, admins and managers can add, test and delete endpoints; everyone else sees the list. If you also use the AI agent features, the agent ID on the same page feeds the chat endpoint. For the voice side of the product see Setting Up an AI Agent in Call.

Frequently asked questions

How do I get an API key?

Keys are issued by the operator of your workspace; they cannot be created in the app. Ask for one and say which scopes it needs. The full key is shown once when it is issued.

What does a 429 response mean?

The key has used up its requests for the current minute. Wait for the number of seconds in the X-RateLimit-Reset header, then try again, and spread bulk work over a longer period.

How do I check that a webhook really came from Call?

Compute an HMAC-SHA256 of the timestamp and body with your signing secret and compare it with the signature header. The API reference shows examples in Node.js and Python.

Can I send webhooks to a local development server?

Not directly. Endpoints must be public https addresses, so use a tunnelling tool that exposes your local server on one.

Why was my API call to place a call refused?

Calls placed through the API go through the same compliance check as calls from the desk. A number on the do-not-call list or outside calling hours is refused.

Who can see and change webhooks?

Everyone can read the list, but only owners, admins and managers can add, test or delete endpoints.

Open the Call API reference and add a webhook endpoint

In the demo console you can try incoming calls in a simulation.

Related guides