Phone numbers

Provision, release, and manage Twilio phone numbers for voice agents

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.

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "all" or "list".

data · object

Show properties

search · string

Filter by phone number digits.

country_code · string

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

status · string

Filter by status.

is_transfer · boolean

Filter by transfer vs main numbers.

agent_id · string

Filter to a specific genie.

limit · number · default: "50"

Results per page. Maximum 500.

offset · number · default: "0"

Number of results to skip.

adminMode · boolean · default: "false"

Admin only. View all phone numbers across the platform.

success · boolean

data · object

Show properties

items · array

Array of phone number objects.

count · number

Total number of matching records.

limit · number

The limit that was applied.

offset · number

The offset that was applied.

cURL

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

---

Get phone number

Retrieves a single phone number by ID with profile enrichment.

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "get".

id · string · required

The phone number record ID.

---

Stats

Returns aggregated statistics across phone numbers.

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "stats".

data · object

Show properties

total · number

Total phone number count.

active · number

Active phone numbers.

inactive · number

Inactive phone numbers.

---

Export

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

resource · string · required

Must be "phone-numbers".

action · 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.

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "provision".

data · object · required

Show properties

agent_id · string · required

Genie UUID to assign the number to.

country_code · string

Country for number provisioning.

---

Release

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

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "release".

id · 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.

resource · string · required

Must be "phone-numbers".

action · string · required

Must be "update".

id · string · required

The phone number record ID to update.