Skip to main content

Release Phone Numbers

Releases (deletes) one or more phone numbers from the Telnyx account and marks them as released in the agency_phone_numbers database table. This is a destructive, permanent action -- released numbers cannot be recovered. Requires explicit confirmation.

Endpoint​

PropertyValue
Function Namephone-numbers-release
HTTP MethodPOST
AuthenticationSupabase JWT (Bearer token)
Required Roleagency_owner only

Request​

Headers​

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

Body​

FieldTypeRequiredDescription
phone_number_idsarray of string (UUIDs)YesArray of phone number record IDs to release
confirmbooleanYesMust be true to confirm the destructive action

Example:

{
  "phone_number_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "confirm": true
}

Response​

Full Success (200)​

{
  "success": true,
  "released": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+19705551234"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "phone_number": "+19705555678"
    }
  ],
  "failed": [],
  "summary": {
    "total_requested": 2,
    "released_count": 2,
    "failed_count": 0
  },
  "message": "Successfully released 2 phone number(s)"
}

Partial Success (207)​

Returned when some numbers were released successfully and others failed.

{
  "success": false,
  "released": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+19705551234"
    }
  ],
  "failed": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "phone_number": "+19705555678",
      "error": "Telnyx error: 422"
    }
  ],
  "summary": {
    "total_requested": 2,
    "released_count": 1,
    "failed_count": 1
  },
  "message": "Released 1 number(s), 1 failed"
}

Numbers that were already in released status are included in the released array with a note: "Already released" field.

If a Telnyx deletion succeeds but the subsequent database update fails, the failed entry will include "telnyx_released": true to indicate the number was removed from Telnyx but the database record was not updated.

Error Responses​

StatusCondition
400phone_number_ids array is missing or empty
400confirm is not set to true
400Telnyx API key is not configured for the agency
401Missing or invalid authorization header
403Authenticated user does not belong to an agency
403User role is not agency_owner (only owners can release numbers)
404None of the provided phone number IDs belong to the user's agency
405HTTP method is not POST
500Database query to fetch phone numbers failed
500All phone numbers failed to release
500Unexpected server error

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 agency_owner role can release numbers. This is stricter than other phone number operations because releasing is a destructive action.
  • Retrieves the agency's decrypted Telnyx API key by calling get_agency_credentials.
  • Validates that phone_number_ids is a non-empty array and that confirm is exactly true.
  • Fetches the matching phone number records from agency_phone_numbers scoped to the agency.
  • Processes each phone number sequentially:
    1. Already released: If the number's status is already released, it is added to the released results with a note and skipped.
    2. Telnyx deletion: Calls the Telnyx DELETE /v2/phone_numbers/{id} endpoint using the phone_number_id if available, or falls back to the phone number string. A 404 response from Telnyx is treated as acceptable (the number may no longer exist on Telnyx's side).
    3. Database update: Updates the agency_phone_numbers record, setting status to released, is_active to false, agent_mapping_id and direction to null, and released_at to the current timestamp.
    4. If either the Telnyx deletion or database update fails, the number is added to the failed array with an error description.
  • Returns the overall result:
    • HTTP 200 if all numbers were released successfully.
    • HTTP 207 (Multi-Status) if some succeeded and some failed.
    • HTTP 500 if all numbers failed to release.

Database Tables Read​

  • users -- to resolve the caller's agency_id and role
  • agency_phone_numbers -- to fetch the numbers to be released

Database Tables Written​

  • agency_phone_numbers -- updates each released number's status, is_active, agent_mapping_id, direction, and released_at

Database Functions Called​

  • get_agency_credentials -- to retrieve the decrypted Telnyx API key

External APIs Called​

  • Telnyx DELETE /v2/phone_numbers/{phone_number_id} -- deletes the phone number from the Telnyx account