aethexDocs
Dashboard

API Reference

Phone Numbers API

Register and manage the phone numbers your account uses for inbound and outbound voice. Numbers can be backed by either a Twilio account (provider: "twilio") or a tenant-owned SIP trunk (provider: "sip"). For Twilio, registration validates the number against your connected Twilio account and wires the Voice URL on Twilio when agent_id is set. For SIP, create or onboard the trunk first with the SIP Trunks API, then register additional numbers here when needed. Routing rules (voicemail / forward / hangup) attach independently and apply when no agent answers. Reads use phone_numbers:read; create, update, and delete use phone_numbers:write.

Base URL
https://api.aethexai.com/api/v1
Endpoints
8
Scopes
phone_numbers:readphone_numbers:write
GET/phone-numbers

Every phone number registered on your account, newest first.

List Phone Numbers

Returns every phone number on your account that is not released, newest first. Twilio and SIP numbers appear in the same list; use the provider field to tell them apart.

Path & Query

2
  • offsetintegeroptional

    Number of results to skip. Default 0, minimum 0.

  • limitintegeroptional

    Maximum results per page. Default 50, range 1–1000.

POST/phone-numbers/twilio/register

Register a Twilio number on your account and (optionally) point it at an agent.

Register Twilio Number

Connects an existing Twilio number to your Aethex account. Pass the twilio_account_id you got from `POST /twilio-accounts` so Aethex knows which Twilio account owns the number. The registration is rejected if the number is not present on that Twilio account. The phone_number must be valid E.164 (+ followed by 1–15 digits) and not already registered to another account.Wiring it up for inbound. When agent_id is supplied, the same request also configures the number's Voice URL on Twilio so inbound calls land here automatically; you do not have to touch the Twilio console. If Twilio rejects the binding, the registration fails as a whole and no record is created. Omit agent_id to register without an inbound binding; you can PATCH one on later, and Aethex re-configures the Voice URL at that point.

Request body

4
  • phone_numberstringrequired

    E.164 phone number to register (e.g. +14155551234). Must exist on the supplied Twilio account.

  • twilio_account_idstringrequired

    UUID returned from POST /twilio-accounts for the Twilio account that owns this number.

  • friendly_namestringoptional

    Human-readable label (max 255 characters, plain text). Default "".

  • agent_idstringoptional

    Agent to handle inbound calls on this number. When set, the Voice URL is configured on Twilio as part of this request. Omit or pass null to register without an agent; you can PATCH one on later.

Errors

6
404Agent not found

The supplied agent_id does not exist on your account.

Check the agent ID with GET /agents, or omit agent_id to register without one.

409Phone number already registered

This number is already active on an account; the same E.164 cannot be registered twice anywhere.

The message says which case you are in. On this account: release it with DELETE /phone-numbers/{id}, whose id the message carries, or choose a different number. On another account: contact support — a registration cannot be moved self-service.

422Invalid Twilio account

The twilio_account_id does not match an active Twilio account on your account.

Register your Twilio account first with POST /twilio-accounts, then pass the returned id here.

422Number not in Twilio account

The phone_number is not present on the Twilio account you referenced.

Purchase or port the number into that Twilio account first. Verify in the Twilio console under Phone Numbers → Manage → Active Numbers.

422Validation error

phone_number is not valid E.164, twilio_account_id is not a valid UUID, or friendly_name exceeds 255 characters or contains HTML.

Match the field constraints above. E.164 is + followed by 1–15 digits; the first digit must not be 0.

503Twilio unreachable

Twilio did not respond in time while verifying the number or configuring the Voice URL.

Retry with backoff. Check status.twilio.com first if it persists; no record is created on failure, so a successful retry creates it cleanly.

POST/phone-numbers/sip/register

Attach another number to an active SIP trunk.

Register SIP Number

Registers a phone number on an active SIP trunk so calls to that number route through your carrier. The trunk_id must reference a tenant-owned trunk from GET /sip-trunks; for first-time outbound SIP setup, prefer POST /sip-trunks/onboard because it creates the trunk and registers its numbers in one operation. The number cannot already be registered on any account (Twilio or SIP). outbound_enabled is the kill switch for outbound calls placed from this number; set true to allow it as a from_number on POST /calls/trigger. Pass an inbound object to set initial routing rules, or set them later with POST /phone-numbers/{id}/routing.

Request body

6
  • phone_numberstringrequired

    E.164 phone number to register.

  • trunk_idstringrequired

    UUID of an active SIP trunk in your account. Create one with POST /sip-trunks/onboard or POST /sip-trunks.

  • friendly_namestringoptional

    Human-readable label (max 255 characters, plain text). Default "".

  • agent_idstringoptional

    Agent to handle inbound calls on this number.

  • outbound_enabledbooleanoptional

    Allow this number to place outbound calls. Default false.

  • inboundobjectoptional

    Initial routing rules: { fallback_action, fallback_number?, max_ring_seconds? }. See Set Routing Rules below for the field constraints.

Errors

5
404SIP trunk not found

The supplied trunk_id does not match a SIP trunk visible to your account.

Use a trunk ID from GET /sip-trunks for this account. Cross-account trunk IDs intentionally return the same 404.

404Agent not found

The supplied agent_id does not exist on your account.

Check the agent ID with GET /agents, or omit it.

409Phone number already registered

This number is already active on an account.

The message says which case you are in. On this account: release it with DELETE /phone-numbers/{id}, whose id the message carries, or choose a different number. On another account: contact support — a registration cannot be moved self-service.

422SIP trunk inactive

The referenced SIP trunk exists for your account but is not active yet.

Wait until the trunk status is active, then retry the registration.

422Validation error

phone_number is not valid E.164, trunk_id is not a valid UUID, or inbound.fallback_action is forward without a fallback_number.

Match the field constraints above. fallback_number is required when fallback_action is forward.

POST/phone-numbers/africastalking/register

A short code that receives texts, on your linked Africa's Talking account.

Register an Africa's Talking short code

A short code is a phone number row like any other: it carries the agent that answers, the answering role and the customer threads. What sits behind it is your linked Africa's Talking account instead of a Twilio one. The row is created with sms_inbound off. Turn it on with PATCH /phone-numbers/:id as for any number; the same guards apply (an agent must be bound, the account must be active), and there is no carrier round trip. Africa's Talking then needs the account's inbound callback URL, shown once when you link the account or by POST /messaging-accounts/:id/inbound-callback. Alphanumeric sender IDs are not accepted here: a name cannot be replied to, so it stays on the messaging account as the call-time sender. sms_inbound is refused until the account has an inbound callback URL issued; the response's messaging_account_id shows which account the short code sits on.

Request body

4
  • shortcodestringrequired

    The short code, 3 to 8 digits, no plus sign and no country code (for example 29361). It is returned as phone_number.

  • messaging_account_idstringrequired

    UUID of your active Africa's Talking account from GET /messaging-accounts. Its username and API key send and receive on this short code.

  • friendly_namestringoptional

    Human-readable label (max 255 characters, plain text). Default "".

  • agent_idstringoptional

    Agent that answers texts sent to this short code. Required before sms_inbound can be turned on.

Errors

5
404Messaging account not found

The supplied messaging_account_id does not exist on your account.

Use an ID from GET /messaging-accounts, or link an account first with POST /messaging-accounts.

404Agent not found

The supplied agent_id does not exist on your account.

Check the agent ID with GET /agents, or omit it.

409Short code already registered

This short code is already registered on your account, on this messaging account or on one you linked before. The same digits held under someone else's Africa's Talking account, in another country, register separately.

The message carries the id of your existing row. If you relinked your Africa's Talking account, move the short code with PATCH /phone-numbers/:id and the new messaging_account_id instead of registering it again. Otherwise release it with DELETE /phone-numbers/:id, or use a different short code.

422Messaging account cannot carry this short code

The messaging account is released, or it is not an Africa's Talking account.

Link an active Africa's Talking account and register the short code under it.

422Validation error

shortcode is not 3 to 8 digits (an E.164 number or a sender name was given), or messaging_account_id is not a valid UUID.

Send the bare digits of the short code. An E.164 number belongs on the Twilio or SIP route; a sender name belongs on the messaging account.

GET/phone-numbers/:id

Fetch a single phone number record.

Get Phone Number

Returns one phone number on your account. Released numbers are hidden and return 404.

Path & Query

1
  • idstringrequired

    Phone number UUID, from any list or register response.

Errors

1
404Phone number not found

No active phone number with this ID exists on your account.

Check the ID with GET /phone-numbers.

PATCH/phone-numbers/:id

Reassign the agent, toggle outbound, or rewrite routing on an existing number.

Update Phone Number

Partial update; only the fields you send change. On a Twilio number, changing agent_id (assign, switch, or clear) re-configures the Voice URL on Twilio in the same request, so the same Twilio-side errors apply. Pass null for agent_id to clear the inbound binding; pass null for routing_rules to clear it. Twilio outbound is governed by your Twilio account settings.

Path & Query

1
  • idstringrequired

    Phone number UUID.

Request body

10
  • friendly_namestringoptional

    Updated label (max 255 characters, plain text).

  • agent_idstringoptional

    New agent UUID, or null to unassign. On Twilio numbers, this re-binds (or unbinds) the Voice URL on Twilio.

  • routing_rulesobjectoptional

    Routing rules object to replace the current ones, or null to clear. See Set Routing Rules below for the shape.

  • outbound_enabledbooleanoptional

    Reserved for support-managed carriers. Has no effect on Twilio numbers.

  • trunk_idstringoptional

    SIP numbers only. Re-points the number at another of your SIP trunks: outbound calls from this number dial through the new trunk from the next call. The carrier is not contacted and the trunk itself is unchanged. The trunk must be active; cannot be null. Returns 422 on a Twilio number. This is the number's outbound trunk link; it is only consulted as an inbound fallback when the trunk is inbound-type, so pointing it at an outbound-only trunk (the normal case for numbers set up via SIP trunk onboarding) is expected.

  • sms_senderbooleanoptional

    Let this number send text messages: booking links and the messages your agents send during a call. Several of your numbers may send — each agent texts from the one named on it (sms_sender_number_id), so a sales line and a support line each send under their own identity. The number must be active and backed by your own Twilio account; Twilio is asked whether it can send text messages at all, and a voice-only line is refused. This is how a Twilio tenant enables texting: there is no messaging account to link. Turning it off on your default sender is refused on its own — send sms_sender_default: false with it, or make another number the default first. The messages themselves are written under Text messages.

  • sms_sender_defaultbooleanoptional

    Make this number the one an agent texts from when no number was named on it. You have exactly one, so setting it here moves it from whichever number held it — no window in which nothing would send. The number must also send (sms_sender), already or in the same request; a default that cannot send is a fallback resolving to nothing.

  • sms_inboundbooleanoptional

    Let this number receive text messages sent to it. Whether it also *answers* them is the agent bound to it: with one, the agent replies; with none, the message is recorded and nothing is sent, which is what a number used only to collect replies wants. Refused unless the number is active, sits on your own Twilio account, the carrier says it can carry texts, and the number is not bound to a TwiML App for messaging. An app's webhook overrides the number's, so texts would never reach us. One override we cannot see: a number belonging to a Twilio Messaging Service has that service's inbound webhook win as well, and it is not readable from the number, so detach it there yourself before turning this on. Your call routing is untouched: a number whose calls an Elastic SIP Trunk or a voice TwiML App already routes keeps sending them there, and can receive texts all the same. If such a number still carries a Voice URL we wrote before its calls moved, we clear it — never one that is not ours — so after you detach the trunk or the app, re-assign the number's agent to have its calls come back to us — sending the agent it already has is enough.

  • acknowledge_no_repliesbooleanoptional

    Designate this number as a sender although it does not answer texts, having understood what that costs. Without this field the request is refused: someone texted from a line that cannot answer has no way to reply, and their STOP reaches nobody. The refusal is not absolute because two legitimate setups cannot answer — a US number in a Messaging Service, whose service webhook wins over the number's own, and a Twilio line a SIP tenant holds purely to send from. Ignored where the number does answer. When you gave it is kept in replies_acknowledged_at, and cleared as soon as the line answers or stops sending.

  • messaging_account_idstringoptional

    Africa's Talking short codes only: move the short code to another of your active messaging accounts, for example after rotating an API key (which links a new account). Validated like a grant; while sms_inbound is on, the new account must already have an inbound callback URL.

Errors

6
404Phone number not found

No active phone number with this ID exists on your account.

Check the ID with GET /phone-numbers.

404Agent not found

The new agent_id does not exist on your account.

Check the agent ID with GET /agents.

422Validation error

A field failed validation (friendly_name, agent_id or trunk_id UUID format, trunk_id on a Twilio number or an inactive trunk), or the linked Twilio account is no longer active.

Match the field constraints above.

409Number cannot be the SMS sender

sms_sender was set on a number that is not active, has no Twilio account, sits on a platform-shared account, or that Twilio reports cannot send text messages.

Designate an active number on your own Twilio account that is SMS-capable.

409This number takes no replies

sms_sender was set on a number without sms_inbound, or sms_inbound was turned off on a number that sends. Either way a recipient's reply — and their STOP — would never reach you.

Turn on sms_inbound for this number, or send the same request again with acknowledge_no_replies: true.

503Twilio unreachable

Twilio did not respond while re-binding the Voice URL, or while checking whether the number can send text messages.

Retry with backoff. Twilio and Aethex stay in sync on retry; the change only commits when Twilio confirms.

DELETE/phone-numbers/:id

Stop accepting calls on a number.

Release Phone Number

Marks the phone number as released so it stops accepting inbound calls and no longer appears in GET /phone-numbers. For Twilio numbers, Aethex also clears the Voice URL on Twilio as part of the same request.

Path & Query

1
  • idstringrequired

    Phone number UUID.

Errors

2
404Phone number not found

No active phone number with this ID exists on your account. Already-released numbers also return 404.

Check the ID with GET /phone-numbers. Releasing twice is not supported; a 404 on the second call means the first one already succeeded.

409Number is your default text sender

The number carries sms_sender_default. Releasing it hands it back to the carrier, and every path that resolves a sender filters on active numbers — so the account would be left unable to send any text message, with nothing to say so.

Make another number the default first, or send {"sms_sender": false, "sms_sender_default": false} on this one, then release it.

POST/phone-numbers/:id/routing

Decide what happens when no agent answers (voicemail, forward, or hangup).

Set Routing Rules

Replaces the inbound routing rules on a phone number. To clear routing rules instead, use PATCH /phone-numbers/{id} with routing_rules: null.

Path & Query

1
  • idstringrequired

    Phone number UUID.

Request body

3
  • fallback_actionstringoptional

    What to do when no agent answers within max_ring_seconds. One of voicemail, forward, or hangup (default).

  • fallback_numberstringoptional

    E.164 number to forward to. Required when fallback_action is forward; ignored otherwise.

  • max_ring_secondsintegeroptional

    How long the number rings before the fallback fires. Default 30, range 5–120.

Errors

2
404Phone number not found

No active phone number with this ID exists on your account.

Check the ID with GET /phone-numbers.

422Invalid routing config

fallback_action is not one of the three allowed values, fallback_number is missing when fallback_action is forward, fallback_number is not valid E.164, or max_ring_seconds is outside 5–120.

Match the field constraints above. To switch away from forward, send the new fallback_action without a fallback_number.