Assign Phone Numbers

A multi-method endpoint that handles listing phone numbers with their assignments, retrieving a single phone number's details, assigning a phone number to an agent, updating phone number settings, and unassigning a phone number from an agent.

Endpoint

Property	Value
Function Name	phone-numbers-assign
HTTP Methods	GET, POST, PATCH, DELETE
Authentication	Supabase JWT (Bearer token)
Required Role	Any agency user for GET; agency_owner or agency_admin for POST, PATCH, and DELETE

---

GET -- List or Retrieve Phone Numbers

Headers

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

Query Parameters

Field	Type	Required	Description
id	string (UUID)	No	If provided, returns a single phone number by its record ID
status	string	No	Filter by status (when listing)
assigned	string	No	Set to true to show only assigned numbers
unassigned	string	No	Set to true to show only unassigned numbers

Response -- Single Number (when id is provided)

{
  "phone_number": {
    "id": "uuid",
    "phone_number": "+19705551234",
    "friendly_name": "Main Line",
    "status": "active",
    "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"
    }
  }
}

Response -- List (when id is not provided)

{
  "phone_numbers": [
    {
      "id": "uuid",
      "phone_number": "+19705551234",
      "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"
      }
    }
  ],
  "available_agents": [
    {
      "id": "agent-uuid",
      "ultravox_agent_id": "uv-agent-id",
      "ultravox_agent_name": "Sales Agent",
      "voice": "en-US-Standard"
    }
  ]
}

The list response always includes available_agents queried from agent_mappings for the agency, ordered by ultravox_agent_name.

---

POST -- Assign Phone Number to Agent

Headers

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

Body

Field	Type	Required	Description
phone_number_id	string (UUID)	Yes	The phone number record ID
agent_mapping_id	string (UUID) or null	No	The agent mapping to assign. Pass null or omit to unassign
friendly_name	string	No	Update the display name
direction	string	No	One of inbound, outbound, both. Defaults to inbound when assigning to an agent

Success Response (200)

{
  "success": true,
  "phone_number": {
    "id": "uuid",
    "phone_number": "+19705551234",
    "agent_mapping_id": "agent-uuid",
    "direction": "inbound",
    "friendly_name": "Main Line",
    "agent_mappings": {
      "id": "agent-uuid",
      "ultravox_agent_id": "uv-agent-id",
      "ultravox_agent_name": "Sales Agent"
    }
  },
  "message": "Phone number assigned to agent successfully"
}

When agent_mapping_id is null or omitted, the message reads "Phone number unassigned successfully" and direction is set to null.

---

PATCH -- Update Phone Number Settings

Headers

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

Body

Field	Type	Required	Description
phone_number_id	string (UUID)	Yes	The phone number record ID
agent_mapping_id	string (UUID) or null	No	Change the assigned agent. Setting to null also clears direction
friendly_name	string	No	Update the display name
direction	string	No	One of inbound, outbound, both
is_active	boolean	No	Enable or disable the phone number

At least one field besides phone_number_id must be provided.

Success Response (200)

{
  "success": true,
  "phone_number": {
    "id": "uuid",
    "phone_number": "+19705551234",
    "friendly_name": "Updated Name",
    "is_active": true,
    "agent_mapping_id": "agent-uuid",
    "agent_mappings": {
      "id": "agent-uuid",
      "ultravox_agent_id": "uv-agent-id",
      "ultravox_agent_name": "Sales Agent"
    }
  }
}

---

DELETE -- Unassign Phone Number from Agent

Headers

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

Query Parameters

Field	Type	Required	Description
id	string (UUID)	Yes	The phone number record ID to unassign

Success Response (200)

{
  "success": true,
  "phone_number": {
    "id": "uuid",
    "phone_number": "+19705551234",
    "agent_mapping_id": null,
    "direction": null
  },
  "message": "Phone number unassigned from agent"
}

---

Error Responses (All Methods)

Status	Condition
400	phone_number_id is missing in the POST or PATCH body
400	PATCH body contains no updatable fields
400	DELETE is missing the id query parameter
401	Missing or invalid authorization header
403	Authenticated user does not belong to an agency
403	User role is not agency_owner or agency_admin (for POST, PATCH, DELETE)
404	Phone number not found or does not belong to the user's agency
404	Agent mapping not found or does not belong to the user's agency (when assigning)
405	HTTP method not supported
500	Database update or query failed
500	Unexpected server error

Behavior

GET

• Authenticates the user and resolves their agency_id.
• If the id query parameter is present, fetches a single phone number record (with joined agent_mappings) scoped to the agency. Returns 404 if not found.
• If id is absent, queries all agency_phone_numbers for the agency ordered by created_at descending. Supports optional filters for status, assigned, and unassigned.
• Always includes a separate query for available_agents from the agent_mappings table.

POST

• Requires the agency_owner or agency_admin role.
• Validates that the phone_number_id exists and belongs to the agency.
• If agent_mapping_id is provided, validates that the agent belongs to the same agency.
• Updates agent_mapping_id on the phone number record. Sets direction to the provided value or defaults to inbound when assigning. Clears direction to null when unassigning.
• Optionally updates friendly_name if provided.

PATCH

• Requires the agency_owner or agency_admin role.
• Validates that the phone_number_id exists and belongs to the agency.
• Builds a partial update object from only the fields that are present in the request body (agent_mapping_id, friendly_name, direction, is_active).
• If agent_mapping_id is provided and non-null, validates the agent belongs to the agency. If set to null, also clears direction.
• Rejects requests where no updatable fields are provided.

DELETE

• Requires the agency_owner or agency_admin role.
• Validates the phone number exists and belongs to the agency.
• Sets agent_mapping_id and direction to null on the record (unassigns without deleting the phone number).

Database Tables Read

• users -- to resolve agency_id and role
• agency_phone_numbers -- to verify ownership and fetch records
• agent_mappings -- to verify agent ownership and provide available agents list

Database Tables Written

• agency_phone_numbers -- updated on POST, PATCH, and DELETE operations

Related Functions

• Search Available Phone Numbers -- search for numbers to purchase
• Purchase Phone Numbers -- purchase new numbers
• List Agency Phone Numbers -- list all numbers with detailed stats
• Release Phone Numbers -- permanently release numbers