> This page is for Cloud Call Center.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Quickstart

> Issue an API key and place your first call from your own system in 3 steps.

The Developer API lets your own systems place calls, read call history, download recordings, and
subscribe to call events. Its base URL is `https://telephony.hams.ai/api/developer/v1`. The API
accepts one credential only: an API key that you create for your account.

## 1. Issue an API key

#### Open the API keys page

Go to **Developer** › **API keys**.

#### Issue the key

Click **Issue key**. Name the key after the system that uses it. Pick its scopes. You can set an expiry date.

#### Copy the key

Copy the key from the confirmation screen before you close the drawer.

![The API keys page shows the prefix, scopes, status, last use, and expiry of each key.](/_fern-img/42d4e88067b94957ad40ff11cdefea5774b125fdd74bf1fc1687ecc54ca26753.webp)

| Scope             | What it lets the key do                                    |
| ----------------- | ---------------------------------------------------------- |
| `calls:write`     | Place calls from any extension in the account              |
| `cdrs:read`       | Read the call history of the account                       |
| `recordings:read` | List, read, and download recordings, and read transcripts  |
| `webhooks:manage` | Create, update, and delete webhooks, and replay deliveries |

The confirmation screen shows the key one time. You cannot recover a key. You can only revoke it and
issue a new one. Save the key in your shell:

```bash
export CCC_KEY=ccc_live_your_key_here
```

> **Warning**
>
> Issue one key for each integration. A key reaches the whole account: every extension, every call,
> and every recording. If each integration has its own key, you can revoke one key and the other
> integrations continue to work.

To revoke a key, use the same page. The key does not work after that. The key stays in the list with
the status revoked and its last-used time. This shows which integration used the key.

## 2. Find the extension to call from

Every call that the API places starts when one of your extensions rings.

#### Open the extensions page

Go to **Settings** › **Extensions**.

#### Pick the extension

Pick the extension that your integration calls from.

#### Copy the extension id

In the **ID** column, click **Copy extension ID**.

## 3. Place a call

```bash
curl -X POST https://telephony.hams.ai/api/developer/v1/calls \
  -H "Authorization: Bearer $CCC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_extension_id": "01924f8e-4a0b-7c3d-9e1f-2a3b4c5d6e7f",
    "to": "+971500000000"
  }'
```

The API answers `202` with the id of the call:

```json
{ "id": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b" }
```

The extension rings first. When the agent answers, the system dials the number through the outbound
route that matches it. The route can rewrite the caller ID and sets the recording policy.

Keep the `id`. It is the one id of the call. You see the same `id` in call history, on the live
board, in every webhook about the call, and in `GET /cdrs`.

## What happens next

The call runs like any other call. A few seconds after the call ends, the system seals its record.
If you subscribe to `call.completed`, the system then sends that webhook. See
[Outbound calls](/cloud-call-center/api/outbound-calls) for the report of a call that does not connect.
See [Webhooks](/cloud-call-center/api/webhooks) for the events you can subscribe to.

## Rate limits

By default, each key can make 10 requests each second across the whole API. Calls that you place have
a separate limit. By default, an account can start 5 new calls each second. A deployment can set both limits. If you exceed a limit, the API answers
`429` with a `Retry-After` header. The header gives the time when the window ends.

## Related

* [Outbound calls](/cloud-call-center/api/outbound-calls)
* [Call history and recordings](/cloud-call-center/api/call-history-and-recordings)
* [Webhooks](/cloud-call-center/api/webhooks)
* [Errors](/cloud-call-center/api/errors)