List available (provider) numbers
GET /api/v1/organizations/telephony-configs/{config_id}/available-numbers — the voice numbers the provider account owns, using the config's saved credentials.
GET /api/v1/organizations/telephony-configs/{config_id}/available-numbersAsks the provider account (using the config's saved credentials) which voice-capable numbers it owns. This powers Fetch from <provider> on a telephony configuration, so you can pick numbers instead of typing them.
This hits the provider, live
The list comes from the provider, not zoxaAI's database, so it reflects what the account owns right now. Nothing is added until you call Add a phone number.
Supported providers
| Provider | What is listed |
|---|---|
| Twilio | Voice-capable incoming phone numbers |
| Plivo | Voice-enabled rented numbers |
| Vobiz | Active voice numbers owned by the account (not sub-accounts) |
| Telnyx | Active phone numbers |
| Vonage | Owned numbers with the VOICE feature (needs the API key and secret) |
| Cloudonix | Phone-number DNIDs on the domain (patterns are skipped) |
| Tata Smartflo | DIDs on the account |
| Asterisk ARI | Not supported: Asterisk has no API that lists numbers. Add them manually. |
Use can_list_numbers from GET /telephony-providers/metadata to tell whether a provider supports this.
Response
200 OK:
{
"numbers": [
{ "address": "+14155550100", "label": "Sales", "note": null, "added": true },
{
"address": "+14155550101",
"label": null,
"note": "Linked to application 2998 in Plivo. Outbound calls work; for inbound calls, link it to this configuration's application in Plivo.",
"added": false
}
],
"truncated": false
}| Field | Type | Description |
|---|---|---|
numbers[].address | string | The number in E.164 (+ and country code). Pass it as address when adding. |
numbers[].label | string | null | Suggested label: the provider's name for the number (Twilio friendly name, Plivo alias, Telnyx tag). |
numbers[].note | string | null | Set when inbound calls on this number would not reach zoxaAI yet, e.g. it is linked to another application or connection on the provider account. Outbound calls are unaffected. |
numbers[].added | bool | Already added to a telephony configuration in this organization. |
truncated | bool | The account owns more than 1,000 numbers; only the first 1,000 are returned. |
Examples
curl https://dashboard.zoxa.ai/api/v1/organizations/telephony-configs/12/available-numbers \
-H "X-API-Key: zsk_..."import httpx
r = httpx.get(
"https://dashboard.zoxa.ai/api/v1/organizations/telephony-configs/12/available-numbers",
headers={"X-API-Key": "zsk_..."},
)
r.raise_for_status()
for n in r.json()["numbers"]:
if not n["added"]:
print(n["address"], n["label"] or "")Errors
| Status | detail | When |
|---|---|---|
400 | "<Provider> rejected the saved credentials. Check them and try again." | The provider refused the config's credentials. |
400 | "This configuration is missing <Provider> credentials. Edit it and try again." | A credential the listing needs is empty (Vonage needs the API key and secret). |
400 | "This provider can't list its numbers. Add them manually." | Asterisk ARI. |
404 | "Telephony configuration not found" | config_id not in your org. |
429 | "<Provider> is rate limiting requests. Try again in a moment." | The provider rate limited the request. |
502 | "Couldn't fetch numbers from <Provider>. Try again shortly." | The provider is unreachable or returned an error. |
The provider's own error body is never returned; it is logged on our side.
Related
List phone numbers
GET /api/v1/organizations/telephony-configs/{config_id}/phone-numbers — every number added to a config, with its inbound target.
Add a phone number
POST /api/v1/organizations/telephony-configs/{config_id}/phone-numbers — register a DID under a config and optionally attach an inbound agent.