Phone numbers Live

Search our carrier-grade SIP network for available phone numbers, claim them, configure inbound routing, and release them. Every claimed number generates an E.164 identifier you can attach to a department or specific agent.

Search available numbers

Returns DIDs (Direct Inward Dial numbers) available for claim from our SIP network in the requested area code.

{ "areaCode": "415", "limit": 10 }

{
  "available": [
    { "e164": "+14155550100", "monthlyCost": "1.00", "locality": "San Francisco, CA" },
    { "e164": "+14155550199", "monthlyCost": "1.00", "locality": "San Francisco, CA" }
  ]
}

Claim a number

Claims an available DID and provisions it on our voice infrastructure. Inbound calls begin routing to your workspace within ~60 seconds. Returns the persisted record.

{
  "e164": "+14155550100",
  "displayName": "Main support",
  "routingStrategy": "all_agents",
  "recordCalls": false,
  "smartHoldEnabled": true
}

List claimed numbers

Cursor-paginated list of numbers owned by this workspace.

Code samples

curl 'https://app.message.com/api/v1/phone-numbers' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT'

const res = await fetch('https://app.message.com/api/v1/phone-numbers', {
  headers: { Authorization: 'Bearer ' + token }
});
const { numbers } = await res.json();

import requests
r = requests.get(
    "https://app.message.com/api/v1/phone-numbers",
    headers={"Authorization": f"Bearer {token}"},
)
numbers = r.json()["numbers"]

require "net/http"
require "json"
uri = URI("https://app.message.com/api/v1/phone-numbers")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{token}"
  http.request(req)
end
numbers = JSON.parse(res.body)["numbers"]

<?php
$ctx = stream_context_create([
  "http" => ["method" => "GET", "header" => "Authorization: Bearer $token"]
]);
$numbers = json_decode(file_get_contents("https://app.message.com/api/v1/phone-numbers", false, $ctx), true)["numbers"];

Get one number

{
  "id": "uuid",
  "version": 1,
  "e164": "+14155550100",
  "displayName": "Main support",
  "routingStrategy": "all_agents",
  "routingTargetId": null,
  "recordCalls": false,
  "smartHoldEnabled": true,
  "voiceProfileId": null,
  "businessHoursOverride": null,
  "monthlyCost": "1.00",
  "createdAt": "2026-05-13T15:00:00Z"
}

Update routing and settings

Updates routing strategy, recording policy, Smart Hold flag, voice profile, business-hours override. Requires expectedVersion.

Release a number

Releases the DID back to the carrier pool. Billing prorates to end of month. Open calls on the number are routed to voicemail before release completes.

Errors

Common pitfalls

• Routing to a specific agent without backup. If that agent is offline the call goes straight to voicemail. Prefer department routing with a small queue.
• Enabling recording without consent disclosure. Set the inbound greeting to include the consent text in two-party-consent regions.
• Reusing a number across workspaces. Not supported. A DID belongs to exactly one workspace at a time.