> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/calling/openapi.json](/docs/api/calling/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Calling

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Phone numbers, calls, recordings and call notes.

Meetings and calls. 17 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/calling/openapi.json](/docs/api/calling/openapi.json).

- `GET /v1/calling/numbers` - List phone numbers (`calling.numbers-list`): [/docs/api/calling/numbers-list.md](/docs/api/calling/numbers-list.md)
- `POST /v1/calling/numbers` - Buy a phone number (`calling.numbers-buy`): [/docs/api/calling/numbers-buy.md](/docs/api/calling/numbers-buy.md)
- `PATCH /v1/calling/numbers/{numberId}` - Update a phone number (`calling.numbers-update`): [/docs/api/calling/numbers-update.md](/docs/api/calling/numbers-update.md)
- `DELETE /v1/calling/numbers/{numberId}` - Release a phone number (`calling.numbers-release`): [/docs/api/calling/numbers-release.md](/docs/api/calling/numbers-release.md)
- `POST /v1/calling/calls` - Start a call (`calling.calls-create`): [/docs/api/calling/calls-create.md](/docs/api/calling/calls-create.md)
- `POST /v1/calling/calls/{callId}/hangup` - Hang up a call (`calling.calls-hangup`): [/docs/api/calling/calls-hangup.md](/docs/api/calling/calls-hangup.md)
- `POST /v1/calling/calls/{callId}/voicemail-drop` - Drop a voicemail greeting on a call (`calling.calls-voicemail-drop`): [/docs/api/calling/calls-voicemail-drop.md](/docs/api/calling/calls-voicemail-drop.md)
- `POST /v1/calling/tokens` - Create a browser calling token (`calling.tokens-create`): [/docs/api/calling/tokens-create.md](/docs/api/calling/tokens-create.md)
- `GET /v1/calling/settings` - Get calling settings (`calling.settings-get`): [/docs/api/calling/settings-get.md](/docs/api/calling/settings-get.md)
- `PATCH /v1/calling/settings` - Update calling settings (`calling.settings-update`): [/docs/api/calling/settings-update.md](/docs/api/calling/settings-update.md)
- `GET /v1/calling/numbers/available` - Search phone numbers for sale (`calling.numbers-available`): [/docs/api/calling/numbers-available.md](/docs/api/calling/numbers-available.md)
- `GET /v1/calling/rates` - Get the call rate for a number (`calling.rates-get`): [/docs/api/calling/rates-get.md](/docs/api/calling/rates-get.md)
- `GET /v1/calling/spend-limit` - Get the calling spend limit (`calling.spend-limit-get`): [/docs/api/calling/spend-limit-get.md](/docs/api/calling/spend-limit-get.md)
- `PATCH /v1/calling/spend-limit` - Update the calling spend limit (`calling.spend-limit-update`): [/docs/api/calling/spend-limit-update.md](/docs/api/calling/spend-limit-update.md)
- `GET /v1/calling/voicemails` - List your voicemail greetings (`calling.voicemails-list`): [/docs/api/calling/voicemails-list.md](/docs/api/calling/voicemails-list.md)
- `POST /v1/calling/voicemails` - Upload a voicemail greeting (`calling.voicemails-create`): [/docs/api/calling/voicemails-create.md](/docs/api/calling/voicemails-create.md)
- `DELETE /v1/calling/voicemails/{voicemailId}` - Delete a voicemail greeting (`calling.voicemails-delete`): [/docs/api/calling/voicemails-delete.md](/docs/api/calling/voicemails-delete.md)

## List phone numbers

`GET /v1/calling/numbers` - operationId `calling.numbers-list`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Lists the workspace's numbers that are not released, newest first, in one page (at most five). `unpaid` is
true when Kenso could not charge a number's month; calls from it are refused until it is paid.

Open to any workspace member.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/numbers)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `CallingNumber`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `numberId` | integer (int64) | The number's id. |
| `e164` | string | The phone number in E.164 format, like `+14155550123`. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code: `US` or `CA`. |
| `numberType` | string | The kind of number: always `local`, since toll-free numbers are not sold yet. |
| `status` | string | The number's state: `ordering` (not assigned yet, not charged), `active`, `releasing` or `released`. |
| `assignedMemberId` | integer (int64) | The member who calls from it; null when no member has it. |
| `cnam` | string | The caller name shown with its calls (US numbers only, at most 15 characters). |
| `monthlyCredits` | integer (int64) | What the number costs each month, in credits. |
| `unpaid` | boolean | True when Kenso could not charge its monthly credits: calls from it are refused until they are paid. |
| `orderedAt` | string (date-time) | When the workspace bought it (UTC). |
| `activatedAt` | string (date-time) | When it turned active and its first month was charged (UTC); null while it is ordering. |
| `releasedAt` | string (date-time) | When it was released (UTC); null until then. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/numbers" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "numberId": 812,
      "e164": "string",
      "countryIso2": "US",
      "numberType": "string",
      "status": "string",
      "assignedMemberId": 812,
      "cnam": "string",
      "monthlyCredits": 1,
      "unpaid": true,
      "orderedAt": "2026-09-23T15:02:11Z",
      "activatedAt": "2026-09-23T15:02:11Z",
      "releasedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Buy a phone number

`POST /v1/calling/numbers` - operationId `calling.numbers-buy`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| The `billing` and `workspace_settings` permissions | Spends credits, price not on the rate card yet (`phone_number_monthly`) | 4,800 requests a minute per API key |

Buys a local number for 100 credits a month. Send `country` and, optionally, the `e164` picked from the
search, an `areaCode` or a `locality`: Kenso searches again and buys `e164` if still offered, else
the first result. `assignedMemberId` gives it to an active member without a number. `cnam` is the caller
name: up to 15 letters, digits, spaces and `.,&-`, US numbers only. The number is `ordering` until
the carrier assigns it; Kenso charges the first month when it turns `active`. Toll-free numbers are not sold.
A number inside the plan's included numbers costs no credits.

Errors:

- `400 validation_failed`: a field is missing or breaks its rule.
- `400 invalid_member`: `assignedMemberId` is not an active member.
- `402 plan_required`: under new pricing the plan lacks Calling, or the workspace is in its self-serve trial,
where Calling stays locked until it pays (`error.refusal` feature `calling`, `requiredPlan` the
plan that unlocks it). Checked before anything else is read or held.
- `402 insufficient_credits`: the credits do not cover the first month; `error.refusal` says how short.
- `402 trial_cap_reached`: the workspace is on the Growth trial and already has its included number
(`error.refusal.metric` `calling_numbers`).
- `409 member_already_has_number`: the member has a number.
- `409 number_limit_reached`: the workspace has five numbers.
- `409 no_numbers_available`: the search found none.
- `503 provider_unavailable`: calling is not set up, or the carrier refused the order. Nothing is charged.

Requires the `workspace_settings` permission and the `billing` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/numbers)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `e164` | string | no | The number to buy, in E.164 format, from the search. Kenso searches again before it buys: when that search no longer offers this number, Kenso buys the first number it offers instead. |
| `country` | string | yes | Required. The number's country, `US` or `CA`; it must be one of the workspace's calling countries. |
| `areaCode` | string | no | Search this three-digit area code. With a US or Canadian `e164` and no area code, Kenso uses the number's own. |
| `locality` | string | no | Search this city, at most 100 characters. |
| `assignedMemberId` | integer (int64) | no | The member who calls from the number. They must be active in the workspace and hold no other number. |
| `cnam` | string | no | The caller name shown with the number's calls: at most 15 letters, digits, spaces and `.,&-`, on US numbers only. |

### Response 201

`data` is a `CallingNumber`.

| Field | Type | Description |
| --- | --- | --- |
| `numberId` | integer (int64) | The number's id. |
| `e164` | string | The phone number in E.164 format, like `+14155550123`. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code: `US` or `CA`. |
| `numberType` | string | The kind of number: always `local`, since toll-free numbers are not sold yet. |
| `status` | string | The number's state: `ordering` (not assigned yet, not charged), `active`, `releasing` or `released`. |
| `assignedMemberId` | integer (int64) | The member who calls from it; null when no member has it. |
| `cnam` | string | The caller name shown with its calls (US numbers only, at most 15 characters). |
| `monthlyCredits` | integer (int64) | What the number costs each month, in credits. |
| `unpaid` | boolean | True when Kenso could not charge its monthly credits: calls from it are refused until they are paid. |
| `orderedAt` | string (date-time) | When the workspace bought it (UTC). |
| `activatedAt` | string (date-time) | When it turned active and its first month was charged (UTC); null while it is ordering. |
| `releasedAt` | string (date-time) | When it was released (UTC); null until then. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/numbers" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "e164": "string",
  "country": "string",
  "areaCode": "string",
  "locality": "string",
  "assignedMemberId": 812,
  "cnam": "string"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "numberId": 812,
    "e164": "string",
    "countryIso2": "US",
    "numberType": "string",
    "status": "string",
    "assignedMemberId": 812,
    "cnam": "string",
    "monthlyCredits": 1,
    "unpaid": true,
    "orderedAt": "2026-09-23T15:02:11Z",
    "activatedAt": "2026-09-23T15:02:11Z",
    "releasedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Update a phone number

`PATCH /v1/calling/numbers/{numberId}` - operationId `calling.numbers-update`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Changes the fields you send. `assignedMemberId` gives the number to an active member without one; null takes
it back. `cnam` sets the caller name, with the rules of the buy; null clears it.

Errors:

- `400 validation_failed`: a field is unknown, of the wrong type or breaks its rule.
- `400 invalid_member`: `assignedMemberId` is not an active member.
- `404 not_found`: no live number has this id in the workspace.
- `409 invalid_state`: the number is releasing, still ordering (for a caller name), or changed meanwhile.
- `409 member_already_has_number`: the member has another number.
- `503 provider_unavailable`: calling is not set up, or the carrier refused the caller name.

Requires the `workspace_settings` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/PATCH/v1/calling/numbers/%7BnumberId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `numberId` | path | integer (int64) | yes | The phone number's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional: `object`.

### Response 200

`data` is a `CallingNumber`.

| Field | Type | Description |
| --- | --- | --- |
| `numberId` | integer (int64) | The number's id. |
| `e164` | string | The phone number in E.164 format, like `+14155550123`. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code: `US` or `CA`. |
| `numberType` | string | The kind of number: always `local`, since toll-free numbers are not sold yet. |
| `status` | string | The number's state: `ordering` (not assigned yet, not charged), `active`, `releasing` or `released`. |
| `assignedMemberId` | integer (int64) | The member who calls from it; null when no member has it. |
| `cnam` | string | The caller name shown with its calls (US numbers only, at most 15 characters). |
| `monthlyCredits` | integer (int64) | What the number costs each month, in credits. |
| `unpaid` | boolean | True when Kenso could not charge its monthly credits: calls from it are refused until they are paid. |
| `orderedAt` | string (date-time) | When the workspace bought it (UTC). |
| `activatedAt` | string (date-time) | When it turned active and its first month was charged (UTC); null while it is ordering. |
| `releasedAt` | string (date-time) | When it was released (UTC); null until then. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/calling/numbers/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "numberId": 812,
    "e164": "string",
    "countryIso2": "US",
    "numberType": "string",
    "status": "string",
    "assignedMemberId": 812,
    "cnam": "string",
    "monthlyCredits": 1,
    "unpaid": true,
    "orderedAt": "2026-09-23T15:02:11Z",
    "activatedAt": "2026-09-23T15:02:11Z",
    "releasedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Release a phone number

`DELETE /v1/calling/numbers/{numberId}` - operationId `calling.numbers-release`

| Permission | Rate limit |
| --- | --- |
| The `billing` and `workspace_settings` permissions | 4,800 requests a minute per API key |

Gives the number back to the carrier and stops its monthly charge; the paid month is not refunded. Returns it
`released`, or `202` with `status: releasing` while the carrier has not taken it back: Kenso then
finishes by itself, and a repeat delete retries.

Errors:

- `404 not_found`: no number has this id in the workspace.
- `409 invalid_state`: the number changed meanwhile.
- `503 provider_unavailable`: calling is not set up.

Requires the `workspace_settings` permission and the `billing` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/DELETE/v1/calling/numbers/%7BnumberId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `numberId` | path | integer (int64) | yes | The phone number's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

Also answers `202`. `data` is a `CallingNumber`.

| Field | Type | Description |
| --- | --- | --- |
| `numberId` | integer (int64) | The number's id. |
| `e164` | string | The phone number in E.164 format, like `+14155550123`. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code: `US` or `CA`. |
| `numberType` | string | The kind of number: always `local`, since toll-free numbers are not sold yet. |
| `status` | string | The number's state: `ordering` (not assigned yet, not charged), `active`, `releasing` or `released`. |
| `assignedMemberId` | integer (int64) | The member who calls from it; null when no member has it. |
| `cnam` | string | The caller name shown with its calls (US numbers only, at most 15 characters). |
| `monthlyCredits` | integer (int64) | What the number costs each month, in credits. |
| `unpaid` | boolean | True when Kenso could not charge its monthly credits: calls from it are refused until they are paid. |
| `orderedAt` | string (date-time) | When the workspace bought it (UTC). |
| `activatedAt` | string (date-time) | When it turned active and its first month was charged (UTC); null while it is ordering. |
| `releasedAt` | string (date-time) | When it was released (UTC); null until then. |

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/calling/numbers/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "numberId": 812,
    "e164": "string",
    "countryIso2": "US",
    "numberType": "string",
    "status": "string",
    "assignedMemberId": 812,
    "cnam": "string",
    "monthlyCredits": 1,
    "unpaid": true,
    "orderedAt": "2026-09-23T15:02:11Z",
    "activatedAt": "2026-09-23T15:02:11Z",
    "releasedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Start a call

`POST /v1/calling/calls` - operationId `calling.calls-create`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Accounts edit | Varies with the request (`call_minutes`); Spends credits, price not on the rate card yet (`call_recording_minutes`) | 4,800 requests a minute per API key |

Calls a person from your browser. Kenso rings your browser first and dials the person when you answer, so log the
browser in with a token from `POST /v1/calling/tokens` before you start. The call comes back with
`status: ringing_rep`.

Send `personId`. `toNumber` must be one of the person's phones; leave it out to call their primary
phone. `fromNumberId` picks the number the call shows; leave it out to use your own number, else the
workspace's first active one. Link the call to an open call task with `callTaskId`, or to a call touch with
`touchId`, which the call's outcome then closes. Send one of them, not both. `recording` (default true) asks
to record the call, and `recordingAllowed` in the response says whether Kenso will.

Before it dials, Kenso checks the person's calling hours in their time zone, opt-outs, the workspace's calling
countries and its limits on calls per person, calls at once and calls per day. It then holds 10 minutes of
credits at `millicreditsPerMinute` and charges the started minutes when the call ends. On a plan with included
calling minutes, the US and Canadian minutes still included come off the hold and the charge.

Errors:

- `400 validation_failed`: `personId` is missing, `callTaskId` is not an open call task of the
person, `touchId` is not a call touch of the person, or both were sent.
- `400 invalid_phone`: `toNumber` is not one of the person's phones.
- `402 plan_required`: under new pricing the plan lacks Calling, or the workspace is in its self-serve trial,
where Calling stays locked until it pays (`error.refusal` feature `calling`, `requiredPlan` the
plan that unlocks it). Checked before anything else is read or held.
- `402 insufficient_credits`: the workspace's credits do not cover the hold.
- `402 calling_limit_reached`: the hold would pass the monthly calling spend limit.
- `402 member_credit_limit_reached`: the hold would pass your own monthly credit limit.
- `402 trial_cap_reached`: the workspace is on the Growth trial and has used its included calling minutes
(`error.refusal.metric` `calling_minutes`).
- `403 forbidden`: the API key is not tied to a member of the workspace.
- `404 not_found`: no person, or no touch for `touchId`, has this id in the workspace.
- `422 call_refused`: Kenso refused the call. `details[0].code` names the reason, such as
`outside_calling_hours`, `opted_out`, `dnc_listed`, `no_phone`, `no_number` or
`daily_limit`. For a reason that passes with time, `details[0].nextAllowedAt` says when to try again.
- `503 provider_unavailable`: calling is not set up yet, or the carrier did not take the call. Nothing is
charged.
- `503 try_again`: another call in the workspace is starting. Retry after the `Retry-After` header.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/calls)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `personId` | integer (int64) | yes | Required. The person to call. |
| `toNumber` | string | no | The number to call, one of the person's phones. Leave it out to call their primary phone. |
| `fromNumberId` | integer (int64) | no | The workspace number the call shows. Leave it out to use your own number, else the workspace's first active one. |
| `callTaskId` | integer (int64) | no | An open call task of the person that this call works. Send this or `touchId`, not both. |
| `touchId` | integer (int64) | no | A call touch of the person that this call works; the call's outcome closes it. Send this or `callTaskId`, not both. |
| `recording` | boolean | no | Record the call where the workspace's settings and the law allow it. Defaults to true. |

### Response 200

`data` is a `CallingCall`.

| Field | Type | Description |
| --- | --- | --- |
| `callId` | integer (int64) | The call's id. |
| `status` | string | The call's status: `ringing_rep` while the member's browser rings. |
| `to` | string | The number called (E.164). |
| `from` | string | The number the call shows (E.164). |
| `fromNumberId` | integer (int64) | The id of the workspace number the call shows. |
| `millicreditsPerMinute` | integer (int64) | What the call costs per started minute, in millicredits: the call to the person plus the member's own side. |
| `consentNoticeWillPlay` | boolean | True when the person hears "This call may be recorded." before the call connects. |
| `recordingAllowed` | boolean | True when Kenso records the call: you asked for it, and the workspace's settings and the law allow it. |
| `lineType` | string | The number's line type, like `mobile` or `fixed_line`. |
| `voicemailDropMode` | string | The call's voicemail drop mode, `off`, `manual` or `auto`, from the workspace's setting and the line type. When it is not off, Kenso listens for a voicemail beep and a greeting can be dropped: with `manual` you ask for the drop, and with `auto` the member's oldest greeting drops by itself. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/calls" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "personId": 812,
  "toNumber": "string",
  "fromNumberId": 812,
  "callTaskId": 812,
  "touchId": 812,
  "recording": true
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "callId": 812,
    "status": "string",
    "to": "string",
    "from": "string",
    "fromNumberId": 812,
    "millicreditsPerMinute": 1,
    "consentNoticeWillPlay": true,
    "recordingAllowed": true,
    "lineType": "mobile",
    "voicemailDropMode": "string"
  }
}
```

## Hang up a call

`POST /v1/calling/calls/{callId}/hangup` - operationId `calling.calls-hangup`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 4,800 requests a minute per API key |

Hangs up both sides of a call you placed. You get `202` with the call's current status, and the call ends
when the carrier confirms. A call that already ended returns `200` with its final status.

Errors:

- `403 forbidden`: you did not place this call, or the API key is not tied to a member.
- `404 not_found`: no call started in Kenso has this id in the workspace.
- `503 provider_unavailable`: calling is not set up yet.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/calls/%7BcallId%7D/hangup)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `callId` | path | integer (int64) | yes | The call's id, from the response that started it. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

Also answers `202`. `data` is a `CallingHangup`.

| Field | Type | Description |
| --- | --- | --- |
| `callId` | integer (int64) | The call's id. |
| `status` | string | The call's status, such as `bridged`, `completed` or `no_answer`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/calls/812/hangup" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "callId": 812,
    "status": "bridged"
  }
}
```

## Drop a voicemail greeting on a call

`POST /v1/calling/calls/{callId}/voicemail-drop` - operationId `calling.calls-voicemail-drop`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 4,800 requests a minute per API key |

Leaves one of your recorded greetings on the person's voicemail. Send `voicemailId`, or leave it out to use
your oldest greeting. The call must be one you placed, the other side must have answered, and the call's
`voicemailDropMode` must not be `off`.

Kenso waits for the voicemail beep, hangs up your side, plays the greeting and then hangs up. The call is logged
with the `voicemail` outcome. When Kenso heard a person rather than a machine, no beep comes and the greeting
plays at once, so ask for the drop after you hear the beep. Do not hang up the call after a drop: that cuts the
greeting off.

You get `202` with `voicemailDropStatus` `requested`, `starting`, `playing` or
`failed`, and `200` once it is `dropped`. Asking again while a drop is under way returns its state.

Errors:

- `403 forbidden`: you did not place this call, or the API key is not tied to a member.
- `404 not_found`: no call started in Kenso has this id in the workspace, or `voicemailId` is not one of
your greetings.
- `409 invalid_state`: the call ended, nobody has answered yet, or voicemail drops are off for it.
- `409 no_voicemail`: you sent no `voicemailId` and have no greeting.
- `503 provider_unavailable`: calling or Kenso's audio storage is not set up yet.
- `503 try_again`: the call is busy. Retry after the `Retry-After` header.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/calls/%7BcallId%7D/voicemail-drop)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `callId` | path | integer (int64) | yes | The call's id, from the response that started it. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voicemailId` | integer (int64) | no | One of your greetings. Leave it out to drop your oldest. |

### Response 200

Also answers `202`. `data` is a `CallingVoicemailDrop`.

| Field | Type | Description |
| --- | --- | --- |
| `callId` | integer (int64) | The call's id. |
| `voicemailId` | integer (int64) | The greeting being dropped. |
| `voicemailDropStatus` | string | Where the drop is: `requested` (waiting for the beep, which never comes when Kenso heard a person rather than a machine: the greeting then plays at once), `starting` (Kenso is hanging up your side), `playing`, `dropped` or `failed`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/calls/812/voicemail-drop" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "voicemailId": 812
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "callId": 812,
    "voicemailId": 812,
    "voicemailDropStatus": "string"
  }
}
```

## Create a browser calling token

`POST /v1/calling/tokens` - operationId `calling.tokens-create`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 4,800 requests a minute per API key |

Returns a WebRTC login token for your browser, with your `sipUsername` and the token's `expiresAt`. The
browser logs in with it so it can answer the calls you start. The token is a secret: keep it in memory and do not
store it. Create a new one when it expires.

Errors:

- `403 forbidden`: the API key is not tied to a member of the workspace.
- `422 call_refused`: calling is not available right now (`calling_disabled`).
- `503 provider_unavailable`: calling is not set up yet, or the carrier cannot be reached.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/tokens)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `CallingToken`.

| Field | Type | Description |
| --- | --- | --- |
| `token` | string | The token the browser logs in with. |
| `sipUsername` | string | The member's SIP username: when a call starts, Kenso rings it. |
| `expiresAt` | string (date-time) | When the token stops working (UTC). Create a new one then. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/tokens" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "token": "string",
    "sipUsername": "string",
    "expiresAt": "2026-09-23T15:02:11Z"
  }
}
```

## Get calling settings

`GET /v1/calling/settings` - operationId `calling.settings-get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns the workspace's calling settings. Until they are saved, the defaults apply and `updatedAt` is null.

Open to any workspace member.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/settings)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `CallingSettings`.

| Field | Type | Description |
| --- | --- | --- |
| `recordingEnabled` | boolean | Record calls, both sides of the conversation. |
| `consentNotice` | string | When the person hears that the call may be recorded: `auto` (where the law asks for it), `always` or `never`, which skips recording where all parties must consent. |
| `voicemailDropMode` | string | Whether members can drop a voicemail greeting: `off`, `manual` (the member drops one) or `auto` (the member's oldest greeting drops by itself). |
| `voicemailToMobile` | boolean | Drop voicemails on mobile numbers too. Turning it on needs `acceptTcpaNotice: true`. |
| `voicemailToMobileAcceptedByMemberId` | integer (int64) | Read-only. The member who last accepted the TCPA notice. Kept when `voicemailToMobile` goes off. |
| `voicemailToMobileAcceptedAt` | string (date-time) | Read-only. When the TCPA notice was last accepted. |
| `allowedCountries` | array of string | The countries the workspace calls, as ISO 3166 alpha-2 codes: `US`, `CA` or both. |
| `dncScrub` | boolean | Saved for an outside do-not-call list Kenso does not check yet. Numbers of opted-out people are always refused. |
| `updatedAt` | string (date-time) | Read-only. When the settings were last saved; null while the workspace uses the defaults. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/settings" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "recordingEnabled": true,
    "consentNotice": "string",
    "voicemailDropMode": "string",
    "voicemailToMobile": true,
    "voicemailToMobileAcceptedByMemberId": 812,
    "voicemailToMobileAcceptedAt": "2026-09-23T15:02:11Z",
    "allowedCountries": [
      "string"
    ],
    "dncScrub": true,
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Update calling settings

`PATCH /v1/calling/settings` - operationId `calling.settings-update`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Changes the fields you send; none takes null. `recordingEnabled` records calls. `consentNotice` says when
the person hears the call may be recorded: `auto` (where the law asks), `always` or `never`, which
skips recording where all parties must consent. `voicemailDropMode` is `off`, `manual` or
`auto`. `voicemailToMobile: true` needs `acceptTcpaNotice: true` in the same body, which records who
accepted and when. `allowedCountries` holds `US`, `CA` or both.
`dncScrub` is saved for an outside do-not-call list Kenso does not check yet; numbers of opted-out people are
always refused.

Errors:

- `400 validation_failed`: a field is unknown, null, of the wrong type or not one of its values, or
`acceptTcpaNotice: true` is missing.

Requires the `workspace_settings` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/PATCH/v1/calling/settings)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional: `object`.

### Response 200

`data` is a `CallingSettings`.

| Field | Type | Description |
| --- | --- | --- |
| `recordingEnabled` | boolean | Record calls, both sides of the conversation. |
| `consentNotice` | string | When the person hears that the call may be recorded: `auto` (where the law asks for it), `always` or `never`, which skips recording where all parties must consent. |
| `voicemailDropMode` | string | Whether members can drop a voicemail greeting: `off`, `manual` (the member drops one) or `auto` (the member's oldest greeting drops by itself). |
| `voicemailToMobile` | boolean | Drop voicemails on mobile numbers too. Turning it on needs `acceptTcpaNotice: true`. |
| `voicemailToMobileAcceptedByMemberId` | integer (int64) | Read-only. The member who last accepted the TCPA notice. Kept when `voicemailToMobile` goes off. |
| `voicemailToMobileAcceptedAt` | string (date-time) | Read-only. When the TCPA notice was last accepted. |
| `allowedCountries` | array of string | The countries the workspace calls, as ISO 3166 alpha-2 codes: `US`, `CA` or both. |
| `dncScrub` | boolean | Saved for an outside do-not-call list Kenso does not check yet. Numbers of opted-out people are always refused. |
| `updatedAt` | string (date-time) | Read-only. When the settings were last saved; null while the workspace uses the defaults. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/calling/settings" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "recordingEnabled": true,
    "consentNotice": "string",
    "voicemailDropMode": "string",
    "voicemailToMobile": true,
    "voicemailToMobileAcceptedByMemberId": 812,
    "voicemailToMobileAcceptedAt": "2026-09-23T15:02:11Z",
    "allowedCountries": [
      "string"
    ],
    "dncScrub": true,
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Search phone numbers for sale

`GET /v1/calling/numbers/available` - operationId `calling.numbers-available`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 12,000 requests a minute per API key |

Returns up to 10 local numbers to buy in `country` (required: `US` or `CA`, one of the workspace's
calling countries), optionally in a three-digit `areaCode` or a city in `locality`.

Errors:

- `400 validation_failed`: `country`, `areaCode` or `locality` is missing or invalid.
- `503 provider_unavailable`: calling is not set up, or the carrier cannot be reached.

Requires the `workspace_settings` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/numbers/available)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | string | no | Required. The country to search, `US` or `CA`; it must be one of the workspace's calling countries. |
| `areaCode` | query | string | no | Only numbers in this three-digit area code, like `415`. |
| `locality` | query | string | no | Only numbers in this city, at most 100 characters. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `AvailableCallingNumber`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `e164` | string | The phone number in E.164 format. Send it as `e164` to buy it. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code: `US` or `CA`. |
| `locality` | string | The city the number belongs to; null when the carrier does not say. |
| `region` | string | The state or province the number belongs to; null when the carrier does not say. |
| `monthlyCredits` | integer (int64) | What the number costs each month once bought, in credits. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/numbers/available" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "e164": "string",
      "countryIso2": "US",
      "locality": "string",
      "region": "string",
      "monthlyCredits": 1
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Get the call rate for a number

`GET /v1/calling/rates` - operationId `calling.rates-get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns what a call to `to` costs per started minute, in millicredits (1,000 are 1 credit), covering both sides
of the call; `recordingMillicreditsPerMinute` is added when it is recorded. An unpriced destination is
`priced: false` with null rates, and calls to it are refused.

Errors:

- `400 invalid_phone`: `to` is missing or not a phone number.

Open to any workspace member.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/rates)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `to` | query | string | no | The number to price, in E.164 format, like `+14155550100`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `CallingRate`.

| Field | Type | Description |
| --- | --- | --- |
| `to` | string | The number you asked about, in E.164 format. |
| `countryIso2` | string | The number's country, as an ISO 3166 alpha-2 code. |
| `lineType` | string | The number's line type, like `mobile`, `fixed_line` or `fixed_line_or_mobile`. |
| `priced` | boolean | True when Kenso has a price for this destination. A call to an unpriced destination is refused. |
| `millicreditsPerMinute` | integer (int64) | The call to the person plus the member's own side of it, per started minute; null when not priced. |
| `recordingMillicreditsPerMinute` | integer (int64) | Added per started minute when the call is recorded; null when not priced. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/rates" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "to": "string",
    "countryIso2": "string",
    "lineType": "mobile",
    "priced": true,
    "millicreditsPerMinute": 1,
    "recordingMillicreditsPerMinute": 1
  }
}
```

## Get the calling spend limit

`GET /v1/calling/spend-limit` - operationId `calling.spend-limit-get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns the monthly calling spend limit and this UTC month's calling spend, in millicredits.
Null is no limit; until one is set it is 2,000 credits with `isDefault: true`. The spend counts call minutes,
recordings and the holds of calls in progress, not number fees.

Open to any workspace member.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/spend-limit)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `CallingSpendLimit`.

| Field | Type | Description |
| --- | --- | --- |
| `monthlyLimitMillicredits` | integer (int64) | The most calls can spend in a month; null means no limit. |
| `isDefault` | boolean | True while the workspace has never set a limit and uses the default, 2,000 credits a month. |
| `spentThisMonthMillicredits` | integer (int64) | The call minutes and recordings charged this month, plus the credits held for calls in progress: the same spend the limit counts. Phone number fees do not count. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/spend-limit" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "monthlyLimitMillicredits": 1,
    "isDefault": true,
    "spentThisMonthMillicredits": 1
  }
}
```

## Update the calling spend limit

`PATCH /v1/calling/spend-limit` - operationId `calling.spend-limit-update`

| Permission | Rate limit |
| --- | --- |
| The `billing` and `workspace_settings` permissions | 4,800 requests a minute per API key |

Sets `monthlyLimitMillicredits`: 1 to 100,000,000, or null for no limit. The next call checks it; a call that
would pass it gets `402 calling_limit_reached`.

Errors:

- `400 validation_failed`: the field is missing, not a whole number or out of range, or another was sent.

Requires the `workspace_settings` permission and the `billing` permission.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/PATCH/v1/calling/spend-limit)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional: `object`.

### Response 200

`data` is a `CallingSpendLimit`.

| Field | Type | Description |
| --- | --- | --- |
| `monthlyLimitMillicredits` | integer (int64) | The most calls can spend in a month; null means no limit. |
| `isDefault` | boolean | True while the workspace has never set a limit and uses the default, 2,000 credits a month. |
| `spentThisMonthMillicredits` | integer (int64) | The call minutes and recordings charged this month, plus the credits held for calls in progress: the same spend the limit counts. Phone number fees do not count. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/calling/spend-limit" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "monthlyLimitMillicredits": 1,
    "isDefault": true,
    "spentThisMonthMillicredits": 1
  }
}
```

## List your voicemail greetings

`GET /v1/calling/voicemails` - operationId `calling.voicemails-list`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Lists your greetings, oldest first. Each member keeps their own, up to five. The first one is the greeting an
`auto` drop plays and the one a drop uses when you name none. `audioUrl` lets you listen to it for 5
minutes, and is missing while Kenso's audio storage is not set up.

Errors:

- `403 forbidden`: the API key is not tied to a member of the workspace.

Open to any workspace member.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/GET/v1/calling/voicemails)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `CallingVoicemail`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `voicemailId` | integer (int64) | The greeting's id. |
| `name` | string | The greeting's name, at most 80 characters. |
| `durationSeconds` | integer (int32) | How long the greeting plays, in whole seconds, rounded up. |
| `format` | string | The audio format, `wav` or `mp3`. |
| `audioUrl` | string | A link to listen to it, valid for 5 minutes. Missing while Kenso's audio storage is not set up. |
| `createdAt` | string (date-time) | When the greeting was uploaded (UTC). |

### Request

```bash
curl -X GET "https://api.ken.so/v1/calling/voicemails" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "voicemailId": 812,
      "name": "string",
      "durationSeconds": 1,
      "format": "string",
      "audioUrl": "https://example.com",
      "createdAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Upload a voicemail greeting

`POST /v1/calling/voicemails` - operationId `calling.voicemails-create`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 480 requests a minute per API key |

Uploads a greeting as `multipart/form-data`. `file` is a WAV or MP3 recording of at most 12 MiB and 60
seconds; Kenso reads the format from the audio itself. `name` is optional, at most 80 characters, and defaults
to `Voicemail`. You can keep up to five greetings.

Errors:

- `400 validation_failed`: `name` is too long, or `file` is missing or too big (`invalid`),
in another format such as WebM or Ogg (`unsupported_audio`), unreadable (`unreadable_audio`) or
longer than 60 seconds (`too_long`).
- `403 forbidden`: the API key is not tied to a member of the workspace.
- `409 voicemail_limit_reached`: you already have five greetings. Delete one first.
- `503 provider_unavailable`: Kenso's audio storage is not set up or cannot be reached.
- `503 try_again`: another of your greetings is uploading. Retry after the `Retry-After` header.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/POST/v1/calling/voicemails)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`multipart/form-data`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string (binary) | no |  |
| `name` | string | no |  |

### Response 201

`data` is a `CallingVoicemail`.

| Field | Type | Description |
| --- | --- | --- |
| `voicemailId` | integer (int64) | The greeting's id. |
| `name` | string | The greeting's name, at most 80 characters. |
| `durationSeconds` | integer (int32) | How long the greeting plays, in whole seconds, rounded up. |
| `format` | string | The audio format, `wav` or `mp3`. |
| `audioUrl` | string | A link to listen to it, valid for 5 minutes. Missing while Kenso's audio storage is not set up. |
| `createdAt` | string (date-time) | When the greeting was uploaded (UTC). |

### Request

```bash
curl -X POST "https://api.ken.so/v1/calling/voicemails" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -F "file=@./file" \
  -F 'name=string'
```

### Example response

```json
{
  "success": true,
  "data": {
    "voicemailId": 812,
    "name": "string",
    "durationSeconds": 1,
    "format": "string",
    "audioUrl": "https://example.com",
    "createdAt": "2026-09-23T15:02:11Z"
  }
}
```

## Delete a voicemail greeting

`DELETE /v1/calling/voicemails/{voicemailId}` - operationId `calling.voicemails-delete`

| Permission | Rate limit |
| --- | --- |
| Accounts edit | 4,800 requests a minute per API key |

Deletes one of your greetings and its audio. A drop that has not played it yet fails.

Errors:

- `403 forbidden`: the API key is not tied to a member of the workspace.
- `404 not_found`: the greeting is not yours or is already deleted.

Requires Accounts edit.

Needs the `calling` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/calling/DELETE/v1/calling/voicemails/%7BvoicemailId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `voicemailId` | path | integer (int64) | yes | The greeting's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 204

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/calling/voicemails/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```http
HTTP/1.1 204 No Content
```

All resources: [/docs.md](/docs.md).
