> ## 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 endpoints for phone numbers

> Search available phone numbers, purchase them for your team, and list numbers already on your account using the Talkturo REST API.

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

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

### Response

```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](/en/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..."
  }'
```

### Response

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

### Response

```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 of purchased phone number objects.
</ResponseField>

<ResponseField name="numbers[].id" type="string">
  Unique identifier for the phone number record.
</ResponseField>

<ResponseField name="numbers[].phone_number" type="string">
  The phone number in E.164 format.
</ResponseField>

<ResponseField name="numbers[].provider" type="string">
  The telephony provider for this number.
</ResponseField>

<ResponseField name="numbers[].status" type="string">
  Current status of the number.
</ResponseField>

<ResponseField name="numbers[].is_trial" type="boolean">
  Whether this is a trial number.
</ResponseField>

<ResponseField name="numbers[].trial_expires_at" type="string">
  Expiry datetime for trial numbers. `null` for paid numbers.
</ResponseField>

<ResponseField name="numbers[].assistant_id" type="string">
  The ID of the assistant this number is currently assigned to. `null` if unassigned.
</ResponseField>

<ResponseField name="numbers[].assistant_name" type="string">
  The name of the assigned assistant. `null` if unassigned.
</ResponseField>

<ResponseField name="numbers[].created_by_email" type="string">
  Email of the team member who purchased this number.
</ResponseField>

<ResponseField name="numbers[].created_by_name" type="string">
  Name of the team member who purchased this number.
</ResponseField>

<ResponseField name="numbers[].created_at" type="string">
  ISO 8601 timestamp of when the number was purchased.
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of phone numbers on the account.
</ResponseField>