Search Available Phone Numbers

Searches the Telnyx API for available phone numbers that can be purchased. Supports filtering by country, area code, city, state, number type, pattern matching, and required features.

Endpoint

Property	Value
Function Name	phone-numbers-search
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any agency user (must have an agency_id)

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Query Parameters

Field	Type	Required	Description
country_code	string	Yes	ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
phone_number_type	string	No	One of local, toll_free, mobile, national
area_code	string	No	National destination code / area code (e.g., 312 for Chicago)
city	string	No	City or locality name
state	string	No	State, province, or region
contains	string	No	Search for specific digits contained in the number
starts_with	string	No	Number prefix to match
ends_with	string	No	Number suffix to match
features	string	No	Comma-separated list of required features: voice, sms, mms, fax, emergency
limit	number	No	Number of results to return (default: 20, max: 100)
quickship	string	No	For US toll-free numbers, return only pre-provisioned numbers (default: true)
best_effort	string	No	Return numbers from nearby areas if exact match not found (default: false)

Response

Success (200)

{
  "phone_numbers": [
    {
      "phone_number": "+19705551234",
      "phone_number_type": "local",
      "features": ["voice", "sms", "mms"],
      "voice_enabled": true,
      "sms_enabled": true,
      "mms_enabled": true,
      "fax_enabled": false,
      "emergency_enabled": false,
      "region_information": [...],
      "country_code": "US",
      "monthly_cost": "1.00",
      "upfront_cost": "1.00",
      "currency": "USD",
      "reservable": false,
      "quickship": false,
      "best_effort": false
    }
  ],
  "meta": {
    "total_results": 20,
    "best_effort_results": 0,
    "country_code": "US",
    "limit": 20
  }
}

Error Responses

Status	Condition
400	country_code query parameter is missing
400	Telnyx API key is not configured for the agency
401	Missing or invalid authorization header
401	Telnyx API key is invalid (proxied from Telnyx 401)
403	Authenticated user does not belong to an agency
405	HTTP method is not GET
500	Unexpected server error
502	Telnyx API returned a non-401 error

Behavior

• Authenticates the user via the Supabase JWT extracted from the Authorization header.
• Looks up the user's agency_id from the users table.
• Retrieves the agency's decrypted Telnyx API key by calling the get_agency_credentials database function with p_agency_id.
• Validates that country_code is present; returns 400 with a hint if missing.
• Builds Telnyx API query parameters by mapping the incoming query parameters to Telnyx's filter[...] format:
  • country_code maps to filter[country_code] (uppercased).
  • area_code maps to filter[national_destination_code].
  • city maps to filter[locality].
  • state maps to filter[administrative_area].
  • contains, starts_with, ends_with map to filter[phone_number][contains], filter[phone_number][starts_with], filter[phone_number][ends_with] respectively.
  • Multiple features are appended as individual filter[features][] parameters.
• Calls the Telnyx GET /v2/available_phone_numbers endpoint.
• Transforms the raw Telnyx response into a simplified format with boolean feature flags (voice_enabled, sms_enabled, etc.), cost information, and region data.
• Returns the transformed phone numbers along with pagination metadata.

Database Tables Read

• users -- to resolve the caller's agency_id

Database Functions Called

• get_agency_credentials -- to retrieve the decrypted Telnyx API key

External APIs Called

• Telnyx GET /v2/available_phone_numbers -- searches available phone number inventory

Related Functions

• Purchase Phone Numbers -- purchase numbers returned by this search
• List Agency Phone Numbers -- list numbers already owned by the agency