Appmint - AI That Builds & Runs Your Entire Business

The Phone module wraps Twilio's number provisioning under a single /phone/* surface. It buys numbers, configures their webhooks, manages routing mode, and tracks them as phone records in the data layer.

Prerequisite: connect Twilio

Phone provisioning requires an active TwilioProvider upstream connection on the org. Configure it through Twilio integration. Without it, every phone endpoint returns "Twilio not configured".

Search available numbers

GET/phone/availableJWT

curl "https://appengine.appmint.io/phone/available?countryCode=US&areaCode=415&smsEnabled=true&limit=10" \
  -H "orgid: my-org" -H "Authorization: Bearer <jwt>"

Field	Type	Description
countryCode	string	ISO country code. Defaults to `US`.
type	string	`local` \| `tollFree` \| `mobile`.
areaCode	string	Area code prefix to filter by.
region	string	Region or state.
contains	string	Pattern matching specific digits (Twilio supports wildcards).
smsEnabled	boolean	Only return SMS-capable numbers.
voiceEnabled	boolean	Only return voice-capable numbers.
mmsEnabled	boolean	Only return MMS-capable numbers.
limit	number	Result count (Twilio default 30).

Purchase a number

POST/phone/numbersJWT

{
  "phoneNumber": "+14155551234",
  "friendlyName": "Sales Line",
  "purpose": "sales",
  "configuration": {
    "voiceConfig": { "recordCalls": true, "transcribeCalls": true },
    "smsConfig": { "autoReplyEnabled": false, "triggerAutomations": true },
    "tracking": { "enabled": true, "campaignId": "spring-2026" }
  }
}

The endpoint:

Calls Twilio's incoming-numbers API to purchase the number
Configures three webhooks on the new SID:
- Voice: /connect/webhook/twilio/voice (or /ivr-menu if routing mode is IVR)
- SMS: /connect/webhook/twilio/sms
- Status: /connect/webhook/twilio/status
Creates a local phone record with the Twilio SID, configuration, and routing defaults
Records usage so the org gets billed for the monthly number fee

Add an existing number

POST/phone/numbers/addJWT

For numbers already on the Twilio account that you want to manage through AppEngine without re-purchasing.

{ "phoneNumber": "+14155551234", "friendlyName": "Existing Main Line", "purpose": "business" }

The webhooks are reconfigured to point at AppEngine; otherwise the number is left untouched.

List, get, update, release

GET/phone/numbersJWT

GET/phone/numbers/{phoneId}JWT

PUT/phone/numbers/{phoneId}JWT

DELETE/phone/numbers/{phoneId}JWT

PUT accepts a partial PhoneConfiguration body — voice, SMS, and tracking sections all optional. DELETE releases the number back to Twilio (irreversible) and deletes the local record.

Routing mode

A phone number is either voice (direct dial through routing assignments) or ivr (runs the IVR flow). Switch with:

POST/phone/numbers/{phoneId}/routingJWT

{ "mode": "ivr" }

mode: 'voice' points the Twilio voice webhook at /connect/webhook/twilio/voice, which dials the user / group / client per the number's assignments. mode: 'ivr' points it at /connect/webhook/twilio/ivr-menu, which runs the IVR flow defined in the number's routing record. See Call routing for the flow.

Setup helper

POST/phone/setupJWT

A convenience that either purchases a new number (purchaseNew: true, areaCode: '415') or imports an existing one. Pass setAsSystem: true to also mark it as the org's primary number — only honored on first call, never overwrites an existing system phone.

System phone

Each org has one "system" phone — the default sender for outbound SMS and the fallback for unassigned IVR routing.

GET/phone/systemJWT

POST/phone/systemJWT

{ "phoneId": "phone-abc-123" }

Verify setup

GET/phone/verifyJWT

Walks through every phone (or just one with ?phoneId=...) and reports webhook configuration, SMS registration status, and any drift between Twilio's view and the local record. Useful after Twilio dashboard edits.

Supported countries

Anything Twilio sells. The actual list is provider-dependent — call GET /phone/available?countryCode=GB etc. to see what's available in your account at any moment. Number availability, regulatory requirements (address proof, identity documents), and pricing are all surfaced through Twilio's API.

A2P 10DLC for US SMS

Numbers purchased for US SMS need A2P 10DLC registration before they can send marketing or transactional SMS at volume. See SMS for the registration flow.

Phone numbers