Trillet AI logo

Search Available Numbers

Search for available phone numbers in a specific country.

GEThttps://api.trillet.ai/v1/api/twilio/available-numbers

Your role needs the phone_number:view permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Query Parameters

countrystringrequired

Country code to search for numbers: US, CA, AU, or GB when it appears in Available Countries. Any other country also needs an addressSid query parameter.

typestringrequired

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.

containsstring

Search for numbers containing specific digits or patterns.

areaCodestring

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.

inStatestring

Only numbers in this state or region (for GB, a city).

limitnumber

Maximum number of results to return. Defaults to 20 for US and CA.

Response Fields

numbersarray

Array of available phone numbers.

phoneNumberstring

The phone number in E.164 format.

friendlyNamestring

A human-readable formatted version of the number.

localitystring

City or locality associated with the number.

regionstring

State or region associated with the number.

capabilitiesobject

voice, SMS, MMS and fax, each true or false.

isoCountrystring

Country code of the number.

filtersobject

Available filter options for the country.

supportedarray

List of supported filter types for the selected country: contains, limit, areaCode and inState for US, CA, AU and GB.

Errors

StatusBodyWhen
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
{
  "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"]
  }
}

Last updated on