REST API endpoints for phone numbers

Phone numbers in Talkturo are the caller IDs your assistants use for inbound and outbound calls. You search for available numbers by country and area code, purchase the ones you want, and then assign them to assistants via the assistants API. Free accounts receive one trial number valid for 5 days. Subscribed accounts can purchase numbers up to the limit of their plan.

Search available phone numbers

POST /api/phone-numbers/search Queries the Telnyx network for available phone numbers matching your criteria. This endpoint does not purchase numbers — it returns a list you can choose from before calling the purchase endpoint.

Request body

object

required

An object containing search filters.

string

required

ISO 3166-1 alpha-2 country code (for example, "US", "GB", "CA").

string

Three-digit area code to filter by (for example, "415" for San Francisco). Only applicable for US and CA numbers.

string

Type of number to search for. One of: local (default), toll-free.

integer

Maximum number of results to return. Defaults to 20.

Example request

curl -X POST https://<your-domain>/api/phone-numbers/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "countryCode": "US",
      "areaCode": "415",
      "numberType": "local",
      "limit": 10
    }
  }'

Response

{
  "success": true,
  "numbers": [
    {
      "phoneNumber": "+14155550101",
      "monthlyPrice": "1.00",
      "setupPrice": "1.00",
      "features": ["voice", "sms"]
    },
    {
      "phoneNumber": "+14155550198",
      "monthlyPrice": "1.00",
      "setupPrice": "1.00",
      "features": ["voice", "sms"]
    }
  ],
  "provider": "telnyx",
  "count": 2
}

array

Array of available phone number objects.

string

The phone number in E.164 format. Pass this value to the purchase endpoint.

string

Recurring monthly cost for the number, in USD.

string

One-time setup fee for the number, in USD.

array

Capabilities supported by this number (for example, "voice", "sms").

string

The telephony provider that supplies this number.

integer

Number of results returned.

Purchase a phone number

POST /api/phone-numbers/purchase Purchases a phone number and adds it to your team’s account. After purchasing, you can assign the number to an assistant using the assign phone numbers endpoint.

Free accounts are limited to one trial number, which expires after 5 days. Subscribed accounts can purchase numbers up to the limit of their plan. A 403 response means you have reached your plan’s limit.

Request body

string

required

The phone number to purchase in E.164 format (for example, "+14155550101"). Use a number returned by the search endpoint.

string

required

The team ID to associate this number with.

string

Optional FQDN connection ID for a custom Talkturo provider configuration.

Example request

curl -X POST https://<your-domain>/api/phone-numbers/purchase \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550101",
    "teamId": "team_01j..."
  }'

Response

{
  "success": true,
  "phoneNumber": {
    "id": "pn_01j...",
    "phone_number": "+14155550101",
    "provider_number_id": "telnyx_...",
    "status": "active",
    "is_trial": false,
    "trial_expires_at": null,
    "message": "Phone number purchased successfully"
  },
  "eligibility": {
    "currentCount": 3,
    "maxAllowed": 10,
    "hasSubscription": true,
    "planName": "Growth"
  }
}

string

Unique identifier for this phone number record. Use this ID when assigning the number to an assistant or campaign.

string

The purchased phone number in E.164 format.

string

The identifier assigned by the telephony provider.

string

Current status of the number (for example, active).

boolean

true if this is a free trial number with an expiry date.

string

ISO 8601 datetime when the trial number expires. null for non-trial numbers.

integer

Number of phone numbers your team currently owns.

integer

Maximum phone numbers allowed by your current plan.

boolean

Whether your account has an active paid subscription.

string

The name of your current plan.

List purchased phone numbers

GET /api/phone-numbers/purchase Retrieves all phone numbers your team has purchased, including which assistant each number is currently assigned to.

Query parameters

string

required

The team ID to list phone numbers for.

Example request

curl "https://<your-domain>/api/phone-numbers/purchase?teamId=team_01j..." \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "numbers": [
    {
      "id": "pn_01j...",
      "phone_number": "+14155550101",
      "provider": "telnyx",
      "status": "active",
      "is_trial": false,
      "trial_expires_at": null,
      "assistant_id": "asst_01j...",
      "assistant_name": "Sales Agent",
      "created_by_email": "alice@example.com",
      "created_by_name": "Alice Johnson",
      "created_at": "2024-01-10T09:00:00Z"
    }
  ],
  "count": 1
}

array

Array of purchased phone number objects.

string

Unique identifier for the phone number record.

string

The phone number in E.164 format.

string

The telephony provider for this number.

string

Current status of the number.

boolean

Whether this is a trial number.

string

Expiry datetime for trial numbers. null for paid numbers.

string

The ID of the assistant this number is currently assigned to. null if unassigned.

string

The name of the assigned assistant. null if unassigned.

string

Email of the team member who purchased this number.

string

Name of the team member who purchased this number.

string

ISO 8601 timestamp of when the number was purchased.

integer

Total number of phone numbers on the account.

Overview

Endpoints

Webhooks

REST API endpoints for phone numbers

Search available phone numbers

Request body

Example request

Response

Purchase a phone number

Request body

Example request

Response

List purchased phone numbers

Query parameters

Example request

Response

​Search available phone numbers

​Request body

​Example request

​Response

​Purchase a phone number

​Request body

​Example request

​Response

​List purchased phone numbers

​Query parameters

​Example request

​Response

Search available phone numbers

Request body

Example request

Response

Purchase a phone number

Request body

Example request

Response

List purchased phone numbers

Query parameters

Example request

Response