Phone numbers

Manage phone numbers provisioned 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

number

default:"50"

Results per page. Maximum 1000.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. View all phone numbers across the platform.

string

Admin only. Scope results to a specific user’s phone numbers.

object

Show properties

string

Filter by phone number digits (non-digit characters are stripped before matching).

string

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

string

Filter by status (for example "active", "inactive").

boolean

When true, return only transfer numbers. When false, return only main numbers.

string

Filter to numbers assigned to a specific genie (UUID).

boolean

object

Show properties

array

Array of phone number objects.

Show item properties

number

Unique phone number record ID (integer).

string

Phone number in E.164 format (for example "+12025551234").

string | null

Human-readable label for the number.

string

Current status (for example "active", "inactive").

string

ISO 8601 timestamp when the number was provisioned.

string | null

Two-letter country code (for example "US").

boolean | null

Whether this is a transfer number rather than a main inbound number.

string

UUID of the genie this number is assigned to.

string

Display name of the assigned genie.

string | null

User ID of the genie’s owner.

string | null

Email of the genie’s owner.

string | null

Full name of the genie’s owner.

number

Total number of matching records.

number

The limit that was applied.

number

The offset that was applied.

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "phone-numbers",
    "action": "all",
    "data": {
      "limit": 50,
      "filters": { "country_code": "US" }
    }
  }'

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

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1234,
        "phone_number": "+12025551234",
        "friendly_name": "Support Line",
        "country_code": "US",
        "status": "active",
        "date_created": "2024-01-15T10:30:00.000Z",
        "is_transfer": false,
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "agent_name": "Customer Support Bot",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "user_email": "owner@example.com",
        "user_name": "Jane Smith"
      }
    ],
    "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 and assigns it to a genie.

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.

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 the carrier. The number may become unavailable for re-provisioning.

Update

Updates phone number configuration.

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