> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Must be `"phone-numbers"`.
Must be `"all"` or `"list"`.
Filter by phone number digits.
Filter by country code (for example `"US"`, `"AU"`).
Filter by status.
Filter by transfer vs main numbers.
Filter to a specific genie.
Results per page. Maximum 500.
Number of results to skip.
Admin only. View all phone numbers across the platform.
Array of phone number objects.
Total number of matching records.
The limit that was applied.
The offset that was applied.
```bash cURL theme={null}
curl -s https://api.helpgenie.ai/v1/phone-numbers \
-H "Authorization: Bearer hg_live_YOUR_KEY"
```
```json Request body theme={null}
{
"resource": "phone-numbers",
"action": "all",
"data": {
"country_code": "US",
"limit": 50
}
}
```
```json Response theme={null}
{
"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.
Must be `"phone-numbers"`.
Must be `"get"`.
The phone number record ID.
***
## Stats
Returns aggregated statistics across phone numbers.
Must be `"phone-numbers"`.
Must be `"stats"`.
Total phone number count.
Active phone numbers.
Inactive phone numbers.
***
## Export
Exports phone numbers as a CSV string. Supports the same filters as the list action.
Must be `"phone-numbers"`.
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.
Must be `"phone-numbers"`.
Must be `"provision"`.
Genie UUID to assign the number to.
Country for number provisioning.
***
## Release
Releases a provisioned phone number. Delegates to the `twilio-handler` edge function.
Must be `"phone-numbers"`.
Must be `"release"`.
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.
Must be `"phone-numbers"`.
Must be `"update"`.
The phone number record ID to update.