---
title: "Search Available Numbers"
api: "GET /v1/api/twilio/available-numbers"
description: "Search for available phone numbers in a specific country."
lastUpdated: "2026-10-29"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

<Note>
Your role needs the `phone_number:view` permission. Otherwise the request fails with `403 {"error": "Insufficient permissions"}`.
</Note>

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="country" type="string" required>
Country code to search for numbers: `US`, `CA`, `AU`, or `GB` when it appears in [Available Countries](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/phone-numbers/available-countries). Any other country also needs an `addressSid` query parameter.
</ParamField>

<ParamField query="type" type="string" required>
`local` or `mobile`. Not required for AU. For `GB`, only `mobile` is available (`local` returns `400` with code `UK_LOCAL_NOT_AVAILABLE`).

Toll-free numbers are not sold through the API. `tollFree` returns `403` with code `TOLL_FREE_NOT_AVAILABLE`, and toll-free numbers are removed from every result.
</ParamField>

<ParamField query="contains" type="string">
Search for numbers containing specific digits or patterns.
</ParamField>

<ParamField query="areaCode" type="string">
Only numbers with this area code. Toll-free area codes (800, 833, 844, 855, 866, 877, 888) return `403` with code `TOLL_FREE_NOT_AVAILABLE`.
</ParamField>

<ParamField query="inState" type="string">
Only numbers in this state or region (for `GB`, a city).
</ParamField>

<ParamField query="limit" type="number">
Maximum number of results to return. Defaults to 20 for US and CA.
</ParamField>

## Response Fields

<ResponseField name="numbers" type="array">
Array of available phone numbers.

<ResponseField name="phoneNumber" type="string">
The phone number in E.164 format.
</ResponseField>

<ResponseField name="friendlyName" type="string">
A human-readable formatted version of the number.
</ResponseField>

<ResponseField name="locality" type="string">
City or locality associated with the number.
</ResponseField>

<ResponseField name="region" type="string">
State or region associated with the number.
</ResponseField>

<ResponseField name="capabilities" type="object">
`voice`, `SMS`, `MMS` and `fax`, each `true` or `false`.
</ResponseField>

<ResponseField name="isoCountry" type="string">
Country code of the number.
</ResponseField>

</ResponseField>

<ResponseField name="filters" type="object">
Available filter options for the country.

<ResponseField name="supported" type="array">
List of supported filter types for the selected country: `contains`, `limit`, `areaCode` and `inState` for US, CA, AU and GB.
</ResponseField>

</ResponseField>

## Errors

| Status | Body | When |
| --- | --- | --- |
| `400` | `{"error": "Country and workspace ID are required."}` | `country` or `x-workspace-id` missing |
| `400` | `{"error": "Type is required for non-AU countries."}` | `type` missing |
| `400` | `{"error": "...", "code": "INVALID_COUNTRY"}` | `GB` isn't available on this deployment |
| `400` | `{"error": "...", "code": "UK_LOCAL_NOT_AVAILABLE"}` | `GB` with `type` `local` |
| `400` | `{"error": "AddressSid is required for this country."}` | Another country without `addressSid` |
| `403` | `{"error": "...", "code": "TOLL_FREE_NOT_AVAILABLE"}` | Toll-free type or area code |
| `500` | `{"error": "Failed to fetch available phone numbers."}` | The provider search failed |

<ResponseExample>
```json
{
  "numbers": [
    {
      "phoneNumber": "+14155551234",
      "friendlyName": "(415) 555-1234",
      "locality": "San Francisco",
      "region": "CA"
    },
    {
      "phoneNumber": "+14155555678",
      "friendlyName": "(415) 555-5678",
      "locality": "San Francisco",
      "region": "CA"
    }
  ],
  "filters": {
    "supported": ["contains", "limit", "areaCode", "inState"]
  }
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
