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.
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.

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.
| Scope | What it allows |
|---|---|
| read | Read contacts, calls, queues, team members, reports and the do-not-call list. |
| write | Create and update contacts, record call outcomes, add numbers to the do-not-call list. |
| calls | Place and end calls. |
| admin | Manage 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.
- 429 rate_limited: back off for the period in the reset header, and spread bulk work over time.
- 403 insufficient_scope: the key lacks the scope on that endpoint's card; request a key with it.
- Other errors: act on the error code, not the message. Codes do not change; wording may.
Handling a failed request
- Read the statusIs it a client error you can fix, or a server error worth retrying?
- Read the codeBranch on the code, never on the message text.
- Back offFor 429, wait for the reset header; for server errors, retry a few times with growing delays.
- Log the detailKeep the endpoint, the code and the time so support can trace it.
- 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
| Good | Poor | |
|---|---|---|
| Signature | Verified on every request | Trusted without checking |
| Reply | 2xx within seconds, work queued for later | Slow processing before replying |
| Duplicates | Safe to receive the same event twice | Creates two records |
| Failures | Alerts when deliveries fail | Silent 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.