List Agency Phone Numbers

Returns all phone numbers owned by the agency from the agency_phone_numbers table, including their agent assignments, status, and capability flags. Also provides summary statistics and optionally a list of available agents for assignment.

Endpoint

Property	Value
Function Name	phone-numbers-list
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
status	string	No	Filter by status: pending, active, suspended, released
assigned	string	No	Set to true to show only numbers assigned to an agent
unassigned	string	No	Set to true to show only unassigned numbers
agent_id	string (UUID)	No	Filter by a specific agent mapping ID
search	string	No	Search by phone number or friendly name (case-insensitive partial match)
include_released	string	No	Set to true to include released numbers (excluded by default)
include_agents	string	No	Set to true to always include available agents in the response
limit	number	No	Number of results per page (default: 50, max: 200)
offset	number	No	Pagination offset (default: 0)

Response

Success (200)

{
  "phone_numbers": [
    {
      "id": "uuid",
      "phone_number": "+19705551234",
      "phone_number_id": "telnyx-id",
      "friendly_name": "Main Line",
      "number_type": "local",
      "country_code": "US",
      "voice_enabled": true,
      "sms_enabled": false,
      "mms_enabled": false,
      "direction": "inbound",
      "monthly_cost": "1.00",
      "currency": "USD",
      "status": "active",
      "is_active": true,
      "purchased_at": "2025-01-15T12:00:00Z",
      "released_at": null,
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z",
      "agent_mapping_id": "agent-uuid",
      "agent_mappings": {
        "id": "agent-uuid",
        "ultravox_agent_id": "uv-agent-id",
        "ultravox_agent_name": "Sales Agent",
        "voice": "en-US-Standard",
        "language_hint": "en",
        "recording_enabled": true
      }
    }
  ],
  "available_agents": [
    {
      "id": "agent-uuid",
      "ultravox_agent_id": "uv-agent-id",
      "ultravox_agent_name": "Sales Agent",
      "voice": "en-US-Standard"
    }
  ],
  "summary": {
    "total": 10,
    "active": 8,
    "pending": 1,
    "suspended": 0,
    "released": 1,
    "assigned": 6,
    "unassigned": 2
  },
  "pagination": {
    "total": 10,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

The available_agents array is populated when include_agents=true is set or when the result set contains fewer than 20 phone numbers.

Error Responses

Status	Condition
401	Missing or invalid authorization header
403	Authenticated user does not belong to an agency
405	HTTP method is not GET
500	Database query for phone numbers failed
500	Unexpected server 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.
• Builds a Supabase query against agency_phone_numbers scoped to the user's agency, selecting phone number fields along with the related agent_mappings record (joined via agent_mapping_id).
• Results are ordered by created_at descending (newest first) and paginated using limit and offset.
• Applies filters:
  • If status is provided, filters to that exact status.
  • If status is not provided and include_released is not true, numbers with status released are excluded.
  • If assigned=true, only numbers where agent_mapping_id is not null are returned.
  • If unassigned=true, only numbers where agent_mapping_id is null are returned.
  • If agent_id is provided, filters to numbers assigned to that specific agent mapping.
  • If search is provided, performs a case-insensitive partial match on phone_number and friendly_name using an OR condition.
• Performs a separate query to compute summary statistics (counts by status and assignment) across all of the agency's phone numbers (unfiltered).
• Conditionally queries agent_mappings for available agents ordered by ultravox_agent_name, included when include_agents=true or when the phone number result set has fewer than 20 entries.
• Returns the phone numbers, available agents, summary, and pagination metadata.

Database Tables Read

• users -- to resolve the caller's agency_id
• agency_phone_numbers -- main query with join to agent_mappings, plus a second query for summary stats
• agent_mappings -- conditionally queried to provide a list of available agents

Related Functions

• Search Available Phone Numbers -- search for new numbers to purchase
• Purchase Phone Numbers -- purchase new numbers
• Assign Phone Numbers -- assign or update phone number configurations
• Release Phone Numbers -- release numbers from the agency