> ## Documentation Index
> Fetch the complete documentation index at: https://docs.persistence.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Telephony

> Manage the phone numbers your agents call from and answer on.

A phone number connects your agents to the telephone network. Buy a number, bind it to the agents that handle its inbound and outbound calls, then use it as the `fromNumber` for outbound campaigns.

## Base URL

```
https://api.persistence.dev
```

<Note>
  These endpoints are served under the public `/v1` prefix.
</Note>

## Authentication

Every request requires a workspace API key in the `X-API-Key` header.

```bash theme={null}
curl https://api.persistence.dev/v1/telephony/phone-numbers \
  --header "X-API-Key: $PERSISTENCE_API_KEY"
```

## Endpoints

<CardGroup cols={1}>
  <Card title="List phone numbers" icon="list" href="/api-reference/telephony/list-phone-numbers">
    `GET /v1/telephony/phone-numbers` — page through the numbers in your workspace.
  </Card>

  <Card title="Buy phone number" icon="cart-shopping" href="/api-reference/telephony/buy-phone-number">
    `POST /v1/telephony/phone-numbers/buy` — buy a number from a provider.
  </Card>

  <Card title="Import phone numbers" icon="download" href="/api-reference/telephony/import-phone-numbers">
    `POST /v1/telephony/phone-numbers/import/manual` — import owned numbers with SIP termination.
  </Card>

  <Card title="Get phone number" icon="file-text" href="/api-reference/telephony/get-phone-number">
    `GET /v1/telephony/phone-numbers/{id}` — retrieve a single number.
  </Card>

  <Card title="Update phone number" icon="pencil" href="/api-reference/telephony/update-phone-number">
    `PATCH /v1/telephony/phone-numbers/{id}` — bind a number to agents.
  </Card>
</CardGroup>

## Phone number fields

| Field                      | Type            | Description                                                                |
| -------------------------- | --------------- | -------------------------------------------------------------------------- |
| `id`                       | string          | Phone number ID.                                                           |
| `phoneNumber`              | string          | The number itself.                                                         |
| `friendlyName`             | string          | Display name for the number.                                               |
| `label`                    | string          | Label applied to the number.                                               |
| `country`                  | string          | Country the number belongs to.                                             |
| `status`                   | string          | Current status of the number.                                              |
| `provider`                 | string          | Telephony provider the number was bought from.                             |
| `providerMonthlyCost`      | number          | Monthly cost charged by the provider.                                      |
| `providerCurrency`         | string          | Currency of the monthly cost.                                              |
| `isCustomerManaged`        | boolean         | Whether you supplied the number rather than buying it through Persistence. |
| `isInboundReady`           | boolean         | Whether the number can receive calls.                                      |
| `isOutboundReady`          | boolean         | Whether the number can place calls.                                        |
| `inboundAgentPublicId`     | string          | ID of the agent that answers inbound calls.                                |
| `inboundAgentName`         | string          | Name of the inbound agent.                                                 |
| `inboundWebhookUrl`        | string          | Webhook called for inbound calls.                                          |
| `outboundAgentPublicId`    | string          | ID of the agent used for outbound calls.                                   |
| `outboundAgentName`        | string          | Name of the outbound agent.                                                |
| `allowedInboundCountries`  | array of string | Countries permitted to call this number.                                   |
| `allowedOutboundCountries` | array of string | Countries this number is permitted to call.                                |
| `sipConfig`                | object          | SIP trunk configuration for the number.                                    |
| `spaceId`                  | string          | Workspace the number belongs to.                                           |
| `createdAt`                | string          | Creation timestamp.                                                        |
| `updatedAt`                | string          | Last update timestamp.                                                     |

### SIP configuration

`sipConfig` describes the SIP trunk settings for the number.

| Field            | Type            | Description                        |
| ---------------- | --------------- | ---------------------------------- |
| `terminationUrl` | string          | SIP termination URL.               |
| `username`       | string          | SIP username.                      |
| `password`       | string          | SIP password.                      |
| `transport`      | string          | SIP transport.                     |
| `ipAllowlist`    | array of string | IP addresses permitted to connect. |

## Buy a phone number

`POST /v1/telephony/phone-numbers/buy` requires both fields below.

| Field         | Type   | Description                                              |
| ------------- | ------ | -------------------------------------------------------- |
| `phoneNumber` | string | Required. The number to buy.                             |
| `provider`    | string | Required. The telephony provider to buy the number from. |

<Note>
  Contact Persistence support for the provider values available to your workspace.
</Note>

The response returns the created phone number. A `402` indicates the purchase could not be completed for billing reasons.

```bash theme={null}
curl --request POST https://api.persistence.dev/v1/telephony/phone-numbers/buy \
  --header "X-API-Key: $PERSISTENCE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phoneNumber": "+15551234567",
    "provider": "PROVIDER"
  }'
```

## Bind a number to agents

`PATCH /v1/telephony/phone-numbers/{id}` updates a number and controls which agents handle its calls.

| Field                      | Description                                       |
| -------------------------- | ------------------------------------------------- |
| `friendlyName`             | Display name for the number.                      |
| `label`                    | Label applied to the number.                      |
| `inboundAgentId`           | Agent that answers inbound calls.                 |
| `outboundAgentId`          | Agent used for outbound calls.                    |
| `useSameForInbound`        | Use the outbound agent for inbound calls as well. |
| `outboundTermination`      | Outbound termination setting for the number.      |
| `allowedInboundCountries`  | Countries permitted to call this number.          |
| `allowedOutboundCountries` | Countries this number is permitted to call.       |

Agent IDs come from the [Agents API](/api-reference/agents/overview). After binding, `isInboundReady` and `isOutboundReady` on the phone number reflect whether the number is ready to handle calls in each direction.

## Pagination and sorting

`GET /v1/telephony/phone-numbers` accepts these query parameters.

| Parameter    | Type    | Description                                  |
| ------------ | ------- | -------------------------------------------- |
| `page`       | integer | Page number.                                 |
| `perPage`    | integer | Items per page.                              |
| `column`     | string  | Sort column, `phone_number` or `created_at`. |
| `order`      | string  | Sort order, `asc` or `desc`.                 |
| `searchText` | string  | Filter numbers by text.                      |

The response wraps the results in a paged object containing `items`, `page`, `perPage`, `totalCount`, `column`, `order`, and `searchText`.

## Errors

Errors return a `code` and an `error` message.

```json theme={null}
{
  "code": "not_found",
  "error": "phone number not found"
}
```

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| `400`  | The request body or a path parameter is invalid.    |
| `401`  | The `X-API-Key` header is missing or invalid.       |
| `402`  | The number could not be bought for billing reasons. |
| `403`  | The key is not permitted to perform the operation.  |
| `404`  | The phone number does not exist.                    |