Phone numbers

Manage phone numbers provisioned via Twilio for voice agents. Phone numbers can be assigned to genies for inbound and outbound calling.

Standard users can only view phone numbers assigned to their own agents. Admin users can view all phone numbers across the platform.

List phone numbers

Returns a paginated list of phone numbers with user profile enrichment.

string

required

Must be "phone-numbers".

string

required

Must be "all" or "list".

object

Show properties

string

Filter by phone number digits.

string

Filter by country code (for example "US", "AU").

string

Filter by status.

boolean

Filter by transfer vs main numbers.

string

Filter to a specific genie.

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. View all phone numbers across the platform.

boolean

object

Show properties

array

Array of phone number objects.

number

Total number of matching records.

number

The limit that was applied.

number

The offset that was applied.

curl -s https://api.helpgenie.ai/v1/phone-numbers \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

{
  "resource": "phone-numbers",
  "action": "all",
  "data": {
    "country_code": "US",
    "limit": 50
  }
}

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "phone-123",
        "number": "+12345678901",
        "friendly_name": "Support Line",
        "country_code": "US",
        "status": "active",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "is_transfer": false,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Get phone number

Retrieves a single phone number by ID with profile enrichment.

string

required

Must be "phone-numbers".

string

required

Must be "get".

string

required

The phone number record ID.

Stats

Returns aggregated statistics across phone numbers.

string

required

Must be "phone-numbers".

string

required

Must be "stats".

object

Show properties

number

Total phone number count.

number

Active phone numbers.

number

Inactive phone numbers.

Export

Exports phone numbers as a CSV string. Supports the same filters as the list action.

string

required

Must be "phone-numbers".

string

required

Must be "export".

CSV columns: Phone Number, Friendly Name, Genie Name, User Email, User Name, Country, Status, Type, Date Provisioned. Maximum 10,000 records.

Provision

Provisions a new phone number via Twilio and assigns it to a genie. Delegates to the twilio-handler edge function.

string

required

Must be "phone-numbers".

string

required

Must be "provision".

object

required

Show properties

string

required

Genie UUID to assign the number to.

string

Country for number provisioning.

Release

Releases a provisioned phone number. Delegates to the twilio-handler edge function.

string

required

Must be "phone-numbers".

string

required

Must be "release".

string

required

The phone number record ID to release.

This will release the phone number from Twilio. The number may become unavailable for re-provisioning.

Update

Updates phone number configuration. Delegates to the twilio-update-number edge function.

string

required

Must be "phone-numbers".

string

required

Must be "update".

string

required

The phone number record ID to update.

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List phone numbers

Get phone number

Stats

Export

Provision

Release

Update

​List phone numbers

​Get phone number

​Stats

​Export

​Provision

​Release

​Update

List phone numbers

Get phone number

Stats

Export

Provision

Release

Update