Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.talkturo.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
filters
object
required
An object containing search filters.
​
filters.countryCode
string
required
ISO 3166-1 alpha-2 country code (for example, "US", "GB", "CA").
​
filters.areaCode
string
Three-digit area code to filter by (for example, "415" for San Francisco). Only applicable for US and CA numbers.
​
filters.numberType
string
Type of number to search for. One of: local (default), toll-free.
​
filters.limit
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
}
​
numbers
array
Array of available phone number objects.
​
numbers[].phoneNumber
string
The phone number in E.164 format. Pass this value to the purchase endpoint.
​
numbers[].monthlyPrice
string
Recurring monthly cost for the number, in USD.
​
numbers[].setupPrice
string
One-time setup fee for the number, in USD.
​
numbers[].features
array
Capabilities supported by this number (for example, "voice", "sms").
​
provider
string
The telephony provider that supplies this number.
​
count
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

​
phoneNumber
string
required
The phone number to purchase in E.164 format (for example, "+14155550101"). Use a number returned by the search endpoint.
​
teamId
string
required
The team ID to associate this number with.
​
connectionId
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"
  }
}
​
phoneNumber.id
string
Unique identifier for this phone number record. Use this ID when assigning the number to an assistant or campaign.
​
phoneNumber.phone_number
string
The purchased phone number in E.164 format.
​
phoneNumber.provider_number_id
string
The identifier assigned by the telephony provider.
​
phoneNumber.status
string
Current status of the number (for example, active).
​
phoneNumber.is_trial
boolean
true if this is a free trial number with an expiry date.
​
phoneNumber.trial_expires_at
string
ISO 8601 datetime when the trial number expires. null for non-trial numbers.
​
eligibility.currentCount
integer
Number of phone numbers your team currently owns.
​
eligibility.maxAllowed
integer
Maximum phone numbers allowed by your current plan.
​
eligibility.hasSubscription
boolean
Whether your account has an active paid subscription.
​
eligibility.planName
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

​
teamId
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
}
​
numbers
array
Array of purchased phone number objects.
​
numbers[].id
string
Unique identifier for the phone number record.
​
numbers[].phone_number
string
The phone number in E.164 format.
​
numbers[].provider
string
The telephony provider for this number.
​
numbers[].status
string
Current status of the number.
​
numbers[].is_trial
boolean
Whether this is a trial number.
​
numbers[].trial_expires_at
string
Expiry datetime for trial numbers. null for paid numbers.
​
numbers[].assistant_id
string
The ID of the assistant this number is currently assigned to. null if unassigned.
​
numbers[].assistant_name
string
The name of the assigned assistant. null if unassigned.
​
numbers[].created_by_email
string
Email of the team member who purchased this number.
​
numbers[].created_by_name
string
Name of the team member who purchased this number.
​
numbers[].created_at
string
ISO 8601 timestamp of when the number was purchased.
​
count
integer
Total number of phone numbers on the account.