Telephony

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

These endpoints are served under the public /v1 prefix.

Authentication

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

curl https://api.persistence.dev/v1/telephony/phone-numbers \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

Endpoints

List phone numbers

GET /v1/telephony/phone-numbers — page through the numbers in your workspace.

Buy phone number

POST /v1/telephony/phone-numbers/buy — buy a number from a provider.

Import phone numbers

POST /v1/telephony/phone-numbers/import/manual — import owned numbers with SIP termination.

Get phone number

GET /v1/telephony/phone-numbers/{id} — retrieve a single number.

Update phone number

PATCH /v1/telephony/phone-numbers/{id} — bind a number to agents.

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.

Contact Persistence support for the provider values available to your workspace.

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

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

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

API reference

Agents

Calls

Accounts and workspaces

Billing

Campaign audience

Campaigns

Number pools

Knowledge bases

Telephony

Base URL

Authentication

Endpoints

List phone numbers

Buy phone number

Import phone numbers

Get phone number

Update phone number

Phone number fields

SIP configuration

Buy a phone number

Bind a number to agents

Errors

​Base URL

​Authentication

​Endpoints

List phone numbers

Buy phone number

Import phone numbers

Get phone number

Update phone number

​Phone number fields

​SIP configuration

​Buy a phone number

​Bind a number to agents

​Pagination and sorting

​Errors

Base URL

Authentication

Endpoints

Phone number fields

SIP configuration

Buy a phone number

Bind a number to agents

Pagination and sorting

Errors