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. Requires adminMode: true.

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.

Add escalation number

Adds an escalation number for live handoff from the browser. When a website visitor asks to talk to a person, they are connected to the escalation number whose description best matches their conversation. If a genie has no escalation numbers, live handoff uses its transfer numbers instead. A genie can have up to 10 escalation numbers.

Adding an escalation number does not turn live handoff on by itself — enable it on the genie with voice_bridge_enabled.

string

required

Must be "phone-numbers".

string

required

Must be "add-escalation".

object

required

Show properties

string

required

UUID of the genie to add the escalation number to.

string

required

Phone number to connect visitors to, in E.164 format (for example "+6495551234").

string

Label for the number, such as "Auckland office". Maximum 60 characters. Defaults to "Escalation Number".

string

When visitors should be connected here, such as "Visitors asking about Auckland bookings". Maximum 300 characters. Leave empty to use this number when nothing more specific matches.

boolean

object

Show properties

string

Escalation number ID. Use this as id for update-escalation and release-escalation.

string

Phone number in E.164 format.

string

Label for the number.

string

When visitors are connected to this number. Empty string when not set.

string

ISO 8601 timestamp when the number was added.

string

Current status (for example "active").

const response = await fetch("https://api.helpgenie.ai/v1", {
  method: "POST",
  headers: {
    Authorization: "Bearer hg_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resource: "phone-numbers",
    action: "add-escalation",
    data: {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      targetNumber: "+6495551234",
      friendlyName: "Auckland office",
      description: "Visitors asking about Auckland bookings",
    },
  }),
});

const { data } = await response.json();

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": "add-escalation",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "targetNumber": "+6495551234",
      "friendlyName": "Auckland office",
      "description": "Visitors asking about Auckland bookings"
    }
  }'

{
  "success": true,
  "data": {
    "id": "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "phoneNumber": "+6495551234",
    "friendlyName": "Auckland office",
    "description": "Visitors asking about Auckland bookings",
    "dateCreated": "2026-10-05T09:20:18.000Z",
    "status": "active"
  }
}

Update escalation number

Updates the phone number, label, and/or description of a genie’s escalation number. Fields you leave out keep their current values.

string

required

Must be "phone-numbers".

string

required

Must be "update-escalation".

string

required

The escalation number’s ID, as returned by add-escalation or listed in the genie’s escalation_phones. The numeric record ID is also accepted.

object

required

Show properties

string

New phone number in E.164 format (for example "+6495551234").

string

New label. Maximum 60 characters.

string

New description of when visitors should be connected here. Maximum 300 characters.

Returns the updated escalation number in the same shape as add-escalation.

const response = await fetch("https://api.helpgenie.ai/v1", {
  method: "POST",
  headers: {
    Authorization: "Bearer hg_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resource: "phone-numbers",
    action: "update-escalation",
    id: "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7",
    data: {
      targetNumber: "+6495559876",
      friendlyName: "Auckland front desk",
    },
  }),
});

const { data } = await response.json();

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": "update-escalation",
    "id": "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "data": {
      "targetNumber": "+6495559876",
      "friendlyName": "Auckland front desk"
    }
  }'

{
  "success": true,
  "data": {
    "id": "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "phoneNumber": "+6495559876",
    "friendlyName": "Auckland front desk",
    "description": "Visitors asking about Auckland bookings",
    "dateCreated": "2026-10-05T09:20:18.000Z",
    "status": "active"
  }
}

Release escalation number

Removes an escalation number from a genie.

string

required

Must be "phone-numbers".

string

required

Must be "release-escalation".

string

required

The escalation number’s ID, as returned by add-escalation or listed in the genie’s escalation_phones. The numeric record ID is also accepted.

await fetch("https://api.helpgenie.ai/v1", {
  method: "POST",
  headers: {
    Authorization: "Bearer hg_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resource: "phone-numbers",
    action: "release-escalation",
    id: "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  }),
});

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": "release-escalation",
    "id": "escalation_7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

{
  "success": true,
  "data": { "success": true }
}

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

Add escalation number

Update escalation number

Release escalation number

Update

​List phone numbers

​Get phone number

​Stats

​Export

​Provision

​Release

​Add escalation number

​Update escalation number

​Release escalation number

​Update

List phone numbers

Get phone number

Stats

Export

Provision

Release

Add escalation number

Update escalation number

Release escalation number

Update