Zum Hauptinhalt springen

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.

Telefonnummern sind die Anrufer-IDs Ihrer Assistenten für Ein- und Ausgang. Sie suchen nach Land und Vorwahl, kaufen Nummern und weisen sie über die Assistenten-API zu. Free-Konten erhalten eine Testnummer (5 Tage); bei bezahlten Tarifen gelten die jeweiligen Nummernlimits.

​
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
erforderlich
An object containing search filters.
​
filters.countryCode
string
erforderlich
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
    }
  }'

​
Antwort

{
  "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
erforderlich
The phone number to purchase in E.164 format (for example, "+14155550101"). Use a number returned by the search endpoint.
​
teamId
string
erforderlich
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..."
  }'

​
Antwort

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

​
Antwort

{
  "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 gekaufter Telefonnummernobjekte.
​
numbers[].id
string
Eindeutiger Bezeichner für den Telefonnummerndatensatz.
​
numbers[].phone_number
string
Die Telefonnummer im E.164-Format.
​
numbers[].provider
string
Der Telefonanbieter für diese Nummer.
​
numbers[].status
string
Aktueller Status der Nummer.
​
numbers[].is_trial
boolean
Ob es sich hierbei um eine Testnummer handelt.
​
numbers[].trial_expires_at
string
Ablaufdatum und Uhrzeit für Testnummern. „null“ für kostenpflichtige Nummern.
​
numbers[].assistant_id
string
Die ID des Assistenten, dem diese Nummer derzeit zugewiesen ist. „null“, wenn nicht zugewiesen.
​
numbers[].assistant_name
string
Der Name des zugewiesenen Assistenten. „null“, wenn nicht zugewiesen.
​
numbers[].created_by_email
string
E-Mail des Teammitglieds, das diese Nummer gekauft hat.
​
numbers[].created_by_name
string
Name des Teammitglieds, das diese Nummer gekauft hat.
​
numbers[].created_at
string
ISO 8601-Zeitstempel des Kaufzeitpunkts der Nummer.
​
count
integer
Gesamtzahl der Telefonnummern im Konto.