REST-API-Endpunkte für Telefonnummern

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

object

erforderlich

An object containing search filters.

string

erforderlich

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
    }
  }'

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
}

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

erforderlich

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

string

erforderlich

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..."
  }'

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"
  }
}

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

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
}

array

Array gekaufter Telefonnummernobjekte.

string

Eindeutiger Bezeichner für den Telefonnummerndatensatz.

string

Die Telefonnummer im E.164-Format.

string

Der Telefonanbieter für diese Nummer.

string

Aktueller Status der Nummer.

boolean

Ob es sich hierbei um eine Testnummer handelt.

string

Ablaufdatum und Uhrzeit für Testnummern. „null“ für kostenpflichtige Nummern.

string

Die ID des Assistenten, dem diese Nummer derzeit zugewiesen ist. „null“, wenn nicht zugewiesen.

string

Der Name des zugewiesenen Assistenten. „null“, wenn nicht zugewiesen.

string

E-Mail des Teammitglieds, das diese Nummer gekauft hat.

string

Name des Teammitglieds, das diese Nummer gekauft hat.

string

ISO 8601-Zeitstempel des Kaufzeitpunkts der Nummer.

integer

Gesamtzahl der Telefonnummern im Konto.

Überblick

Endpunkte

Webhooks

REST-API-Endpunkte für Telefonnummern

Search available phone numbers

Request body

Example request

Antwort

Purchase a phone number

Request body

Example request

Antwort

List purchased phone numbers

Query parameters

Example request

Antwort

​Search available phone numbers

​Request body

​Example request

​Antwort

​Purchase a phone number

​Request body

​Example request

​Antwort

​List purchased phone numbers

​Query parameters

​Example request

​Antwort

Search available phone numbers

Request body

Example request

Antwort

Purchase a phone number

Request body

Example request

Antwort

List purchased phone numbers

Query parameters

Example request

Antwort