Phone numbers

Buy a number on Dialgem or connect one you already own, then choose which agent answers it.

A phone number connects callers to an agent. You can get one three ways:

Way	Use it when
Buy on Dialgem	You want a number quickly, with no carrier account of your own.
Register a number you own	The number lives with a carrier such as Twilio and you want Dialgem to answer it.
Connect a SIP trunk	You want your own carrier to carry the calls. See Connect a SIP trunk.

Buy a number

Search for numbers, then buy one. Dialgem takes the first month from your prepaid balance and the number is ready to use.

Search

GET /v1/phone-numbers/available takes country (default US), type (default local), an area_code of three digits, contains for digits you want in the number, and limit (1 to 50). The reply lists numbers with their location and whether they support voice and SMS, plus the monthly price.

Buy

POST /v1/phone-numbers/buy takes the phone_number exactly as the search returned it (E.164, such as +14155550123), an optional type, and an optional nickname.

Assign an agent

Choose which agent answers it. See below.

curl

curl "https://api.dialgem.com/v1/phone-numbers/available?area_code=415&limit=5" \
  -H "X-API-Key: $DIALGEM_API_KEY"

curl https://api.dialgem.com/v1/phone-numbers/buy \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550123", "nickname": "Front desk" }'

In the dashboard, open Phone numbers and choose to buy a number. The dialog lists numbers as soon as it opens and narrows them as you type an area code.

Who can buy, and where

Buying spends your balance, so it needs credit. People signed in to the dashboard must be an owner or admin. API keys act for the organization. Number purchase is only available when it has been switched on, and only in the countries the search offers.

Register a number you already own

POST /v1/phone-numbers adds a number so Dialgem can answer it. Send the phone_number, a nickname, and the agent that should answer (inbound_agent_id) or place calls (outbound_agent_id).

Choose which agent answers

Set inbound_agent_id on the number, or use PATCH /v1/phone-numbers/{number_id}/assign.

Pin a version. inbound_agent_version fixes the number to a published version. 0 follows the draft, and "latest_published" follows the newest publish.
Split traffic. inbound_agents takes a weighted list of agents so you can run two versions side by side.
Decide per call. An inbound routing webhook can pick the agent, add variables or turn the call away.

A call to a number with no agent assigned is refused rather than answered by a blank agent.

Place calls from a number

outbound_agent_id is the agent used when you place a call from this number. See the from_ field of Create outbound call.

Release a number

DELETE /v1/phone-numbers/{number_id} releases it. Campaigns that use the number pause and need a new one.

Pricing

Numbers have a monthly price, shown in the search results. Calls on a number add the per-minute price. See Billing and pricing.