Purchase Phone Numbers

Purchases one or more phone numbers through the Telnyx Number Orders API and creates corresponding records in the agency_phone_numbers database table. Optionally assigns numbers to an agent immediately upon purchase.

Endpoint

Property	Value
Function Name	phone-numbers-purchase
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner or agency_admin

Request

Headers

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

Body

Field	Type	Required	Description
phone_numbers	array	Yes	Array of phone number objects to purchase (at least one)
phone_numbers[].phone_number	string	Yes	Phone number in E.164 format (e.g., +19705551234). Must match the pattern ^\+[1-9][0-9]{6,14}$
phone_numbers[].friendly_name	string	No	Display name for the phone number
phone_numbers[].agent_mapping_id	string (UUID)	No	Agent mapping ID to assign this number to immediately
customer_reference	string	No	Your custom reference string for the order

Example:

{
  "phone_numbers": [
    {
      "phone_number": "+19705551234",
      "friendly_name": "Main Line",
      "agent_mapping_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "phone_number": "+19705555678"
    }
  ],
  "customer_reference": "my-ref-001"
}

Response

Success (200)

{
  "success": true,
  "order": {
    "id": "telnyx-order-uuid",
    "status": "success",
    "phone_numbers_count": 2,
    "requirements_met": true,
    "created_at": "2025-01-15T12:00:00Z"
  },
  "phone_numbers": [
    {
      "id": "db-record-uuid",
      "agency_id": "agency-uuid",
      "phone_number": "+19705551234",
      "phone_number_id": "telnyx-phone-id",
      "friendly_name": "Main Line",
      "agent_mapping_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "direction": "inbound",
      "status": "active",
      "voice_enabled": true,
      "country_code": "US",
      "purchased_at": "2025-01-15T12:00:00Z"
    }
  ],
  "message": "Phone numbers purchased and activated successfully"
}

When the Telnyx order status is not success, the status field on each phone number record will be pending and purchased_at will be null. The message will read: "Order created. Numbers will be activated once order completes."

Error Responses

Status	Condition
400	phone_numbers array is missing or empty
400	One or more phone numbers are not in valid E.164 format
400	One or more phone numbers are already owned by the agency (status pending or active)
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	User does not belong to an agency
403	User role is not agency_owner or agency_admin
405	HTTP method is not POST
500	Order placed at Telnyx successfully but the database insert for agency_phone_numbers failed. Response includes order_id and order_status for manual recovery
500	Unexpected server error
502	Telnyx API returned a non-401 error when creating the number order

Behavior

• Authenticates the user via the Supabase JWT extracted from the Authorization header.
• Looks up the user's agency_id and role from the users table.
• Enforces that only users with the role agency_owner or agency_admin can purchase numbers.
• Retrieves the agency's decrypted Telnyx API key and application ID by calling get_agency_credentials.
• Validates that every phone number in the request matches E.164 format (^\+[1-9][0-9]{6,14}$).
• Checks the agency_phone_numbers table for duplicates -- numbers with status pending or active that the agency already owns.
• Builds a Telnyx number order payload:
  • If a telnyx_application_id is configured in the agency credentials, it is sent as connection_id to automatically link the numbers to the Telnyx Voice Application.
  • If customer_reference is provided, it is included in the order.
• Calls the Telnyx POST /v2/number_orders endpoint to place the order.
• For each phone number in the request, creates a record in agency_phone_numbers with:
  • status set to active if the order succeeded immediately, or pending otherwise.
  • direction set to inbound if an agent_mapping_id was provided.
  • country_code set to US if the number starts with +1, otherwise null.
  • voice_enabled set to true.
  • purchased_at set to the current timestamp if the order succeeded, otherwise null.
• Returns the Telnyx order summary and the inserted database records.

Database Tables Read

• users -- to resolve the caller's agency_id and role
• agency_phone_numbers -- to check for duplicate numbers already owned

Database Tables Written

• agency_phone_numbers -- inserts new records for each purchased number

Database Functions Called

• get_agency_credentials -- to retrieve the decrypted Telnyx API key and application ID

External APIs Called

• Telnyx POST /v2/number_orders -- creates a phone number purchase order

Related Functions

• Search Available Phone Numbers -- search for numbers before purchasing
• List Agency Phone Numbers -- view purchased numbers
• Assign Phone Numbers -- assign purchased numbers to agents
• Release Phone Numbers -- release numbers you no longer need