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

# REST-API-Endpunkte für Telefonnummern

> Suchen Sie nach verfügbaren Telefonnummern, kaufen Sie sie für Ihr Team und listen Sie Nummern auf, die sich bereits in Ihrem Konto befinden, mithilfe der Talkturo REST API.

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](/de/api-reference/assistants#assign-phone-numbers-to-an-assistant) 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

<ParamField body="filters" type="object" required>
  An object containing search filters.
</ParamField>

<ParamField body="filters.countryCode" type="string" required>
  ISO 3166-1 alpha-2 country code (for example, `"US"`, `"GB"`, `"CA"`).
</ParamField>

<ParamField body="filters.areaCode" type="string">
  Three-digit area code to filter by (for example, `"415"` for San Francisco). Only applicable for US and CA numbers.
</ParamField>

<ParamField body="filters.numberType" type="string">
  Type of number to search for. One of: `local` (default), `toll-free`.
</ParamField>

<ParamField body="filters.limit" type="integer">
  Maximum number of results to return. Defaults to `20`.
</ParamField>

### Example request

```bash theme={null}
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

```json theme={null}
{
  "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
}
```

<ResponseField name="numbers" type="array">
  Array of available phone number objects.
</ResponseField>

<ResponseField name="numbers[].phoneNumber" type="string">
  The phone number in E.164 format. Pass this value to the purchase endpoint.
</ResponseField>

<ResponseField name="numbers[].monthlyPrice" type="string">
  Recurring monthly cost for the number, in USD.
</ResponseField>

<ResponseField name="numbers[].setupPrice" type="string">
  One-time setup fee for the number, in USD.
</ResponseField>

<ResponseField name="numbers[].features" type="array">
  Capabilities supported by this number (for example, `"voice"`, `"sms"`).
</ResponseField>

<ResponseField name="provider" type="string">
  The telephony provider that supplies this number.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of results returned.
</ResponseField>

***

## 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](/de/api-reference/assistants#assign-phone-numbers-to-an-assistant).

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

### Request body

<ParamField body="phoneNumber" type="string" required>
  The phone number to purchase in E.164 format (for example, `"+14155550101"`). Use a number returned by the search endpoint.
</ParamField>

<ParamField body="teamId" type="string" required>
  The team ID to associate this number with.
</ParamField>

<ParamField body="connectionId" type="string">
  Optional FQDN connection ID for a custom Talkturo provider configuration.
</ParamField>

### Example request

```bash theme={null}
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

```json theme={null}
{
  "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"
  }
}
```

<ResponseField name="phoneNumber.id" type="string">
  Unique identifier for this phone number record. Use this ID when assigning the number to an assistant or campaign.
</ResponseField>

<ResponseField name="phoneNumber.phone_number" type="string">
  The purchased phone number in E.164 format.
</ResponseField>

<ResponseField name="phoneNumber.provider_number_id" type="string">
  The identifier assigned by the telephony provider.
</ResponseField>

<ResponseField name="phoneNumber.status" type="string">
  Current status of the number (for example, `active`).
</ResponseField>

<ResponseField name="phoneNumber.is_trial" type="boolean">
  `true` if this is a free trial number with an expiry date.
</ResponseField>

<ResponseField name="phoneNumber.trial_expires_at" type="string">
  ISO 8601 datetime when the trial number expires. `null` for non-trial numbers.
</ResponseField>

<ResponseField name="eligibility.currentCount" type="integer">
  Number of phone numbers your team currently owns.
</ResponseField>

<ResponseField name="eligibility.maxAllowed" type="integer">
  Maximum phone numbers allowed by your current plan.
</ResponseField>

<ResponseField name="eligibility.hasSubscription" type="boolean">
  Whether your account has an active paid subscription.
</ResponseField>

<ResponseField name="eligibility.planName" type="string">
  The name of your current plan.
</ResponseField>

***

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

<ParamField query="teamId" type="string" required>
  The team ID to list phone numbers for.
</ParamField>

### Example request

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

### Antwort

```json theme={null}
{
  "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
}
```

<ResponseField name="numbers" type="array">
  Array gekaufter Telefonnummernobjekte.
</ResponseField>

<ResponseField name="numbers[].id" type="string">
  Eindeutiger Bezeichner für den Telefonnummerndatensatz.
</ResponseField>

<ResponseField name="numbers[].phone_number" type="string">
  Die Telefonnummer im E.164-Format.
</ResponseField>

<ResponseField name="numbers[].provider" type="string">
  Der Telefonanbieter für diese Nummer.
</ResponseField>

<ResponseField name="numbers[].status" type="string">
  Aktueller Status der Nummer.
</ResponseField>

<ResponseField name="numbers[].is_trial" type="boolean">
  Ob es sich hierbei um eine Testnummer handelt.
</ResponseField>

<ResponseField name="numbers[].trial_expires_at" type="string">
  Ablaufdatum und Uhrzeit für Testnummern. „null“ für kostenpflichtige Nummern.
</ResponseField>

<ResponseField name="numbers[].assistant_id" type="string">
  Die ID des Assistenten, dem diese Nummer derzeit zugewiesen ist. „null“, wenn nicht zugewiesen.
</ResponseField>

<ResponseField name="numbers[].assistant_name" type="string">
  Der Name des zugewiesenen Assistenten. „null“, wenn nicht zugewiesen.
</ResponseField>

<ResponseField name="numbers[].created_by_email" type="string">
  E-Mail des Teammitglieds, das diese Nummer gekauft hat.
</ResponseField>

<ResponseField name="numbers[].created_by_name" type="string">
  Name des Teammitglieds, das diese Nummer gekauft hat.
</ResponseField>

<ResponseField name="numbers[].created_at" type="string">
  ISO 8601-Zeitstempel des Kaufzeitpunkts der Nummer.
</ResponseField>

<ResponseField name="count" type="integer">
  Gesamtzahl der Telefonnummern im Konto.
</ResponseField>