Phone numbers API

Authentication and access

These dashboard APIs require an authenticated agent session, not a Verify API key. Searches, purchases, updates and releases require administrator access and the Phones entitlement. Use Settings → Phones → Numbers for an interactive purchase with pricing and address review.

Search available numbers

GET /api/v1/phones/search accepts type=npa, city or tollfree. For npa, supply a three-digit npa; for city, supply city and a two-letter state. Toll-free searches can include a three-digit prefix. quantity defaults to 20 and is capped at 50. The response is { candidates: [...] }; display the returned monthlyPrice rather than hard-coding a price. Availability can change before purchase.

curl 'https://app.message.com/api/v1/phones/search?type=npa&npa=832&quantity=10' \
  -H "Authorization: Bearer $MESSAGE_AGENT_TOKEN"

Purchase a number

POST /api/v1/phones/purchase takes tn, e911 and settings. tn is the selected E.164 number. e911 requires name, address1, city, state and zip; address2 is optional. settings requires displayName, routingStrategy, recordingEnabled and transcriptionMode. transcriptionMode is off, post_call or live.

Routing strategies are all_agents, round_robin, specific_agent, extension, department and external_forward. For department routing supply its UUID as routingTargetId; the department must belong to the workspace and have calls enabled. Optional top-level ivrMenuId and businessHoursRuleId select existing configuration.

HTTP 201 returns { phoneNumber, e911 }. A purchased number can have e911.ok=false: review the returned reason, message and suggested address and correct registration before relying on emergency calling. Do not repeat a purchase after a timeout without checking the numbers list first. A timeout does not prove the purchase failed.

{
  "tn": "+18325550123",
  "e911": {
    "name": "Example business",
    "address1": "Replace with your actual street address",
    "city": "Houston",
    "state": "TX",
    "zip": "77060"
  },
  "settings": {
    "displayName": "Support",
    "routingStrategy": "department",
    "routingTargetId": "00000000-0000-4000-8000-000000000001",
    "recordingEnabled": false,
    "transcriptionMode": "off"
  }
}

List and inspect your numbers

GET /api/v1/phones/numbers accepts page (starting at 1), pageSize (20, 50, 100 or 500) and search. It returns phoneNumbers, total, page and pageSize. Search matches numbers, display names and routing targets.

GET /api/v1/phones/numbers/:id returns { phoneNumber }. For this read endpoint, :id can be the number UUID or its digits. Use the UUID for updates and release. The detail includes resolved ivrMenu and businessHoursRule when configured.

Update a number

PATCH /api/v1/phones/numbers/:id updates only supplied fields and rejects unknown fields. Common fields are displayName, routingStrategy, routingTargetId, recordingEnabled, recordingDisclosureEnabled, transcriptionMode, voicemailEnabled, welcomeGreetingId, voicemailGreetingId, onHoldMusicId, afterHoursGreetingId, ivrMenuId and businessHoursRuleId. Use existing workspace-owned IDs.

The e911 object uses the same address fields as purchase. A failed address validation returns the correction details; do not report emergency registration as complete based on an ordinary settings save. Configure Phone AI through its dedicated setup screen rather than inventing smartHoldEnabled or voiceProfileId purchase fields.

Release a number

DELETE /api/v1/phones/numbers/:id releases the workspace-owned number. This is an administrator action and can make the number unavailable to your business permanently. End active calls and confirm the intended number first. A released number returns 409 already_released; a missing number returns 404 not_found. Do not interpret release as a refund or call transfer.

Handle failures without duplicate purchases

Invalid input returns 400 with field details. Missing authentication or permissions, unavailable product access and provider failures must be handled before continuing. Inspect the error and response status; do not turn every failure into “number unavailable.” After an uncertain purchase, reconcile using the workspace’s numbers list.

The older /phone-numbers routes are not the recommended purchase flow. New integrations should use /phones/search, /phones/purchase and /phones/numbers shown here.