> 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: Buy a phone number

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

One endpoint of [Calling](/docs/api/calling.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## 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"
  }
}
```
