Phone numbers API
List phone numbers
Returns
200.
curl "https://api.dialgem.com/v1/phone-numbers" \
-H "X-API-Key: $DIALGEM_API_KEY"[
{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": {},
"agent_version": {},
"weight": {}
}
]
}
]Register phone number
Request body application/json
Default "custom"
Default 0
Default 0
3 properties
Default 0
Default 1
3 properties
Default 0
Default 1
Show 6 more parameters
Default false
Default false
4 properties
Default "twilio"
Returns
201 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 13 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl -X POST "https://api.dialgem.com/v1/phone-numbers" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155550123"
}'{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}Update phone number
Path parameters
Request body application/json
Default false
Default false
Show 4 more parameters
3 properties
Default 0
Default 1
3 properties
Default 0
Default 1
4 properties
Returns
200 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 13 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl -X PATCH "https://api.dialgem.com/v1/phone-numbers/NUMBER_ID" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nickname": "string"
}'{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}Release phone number
Path parameters
Returns
204 with the resulting object.
curl -X DELETE "https://api.dialgem.com/v1/phone-numbers/NUMBER_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"Assign phone number
Back-compat: assigns the INBOUND agent.
Path parameters
Request body application/json
Returns
200 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 13 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl -X PATCH "https://api.dialgem.com/v1/phone-numbers/NUMBER_ID/assign" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123"
}'{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}Test inbound webhook
Send the routing webhook a sample call and say what the answer would do. Nothing is created or recorded.
Path parameters
Returns
200 with the fields below.
True when your webhook answered with a usable response in time.
How long your webhook took to answer, in milliseconds.
How long a real call waits for your webhook, in milliseconds.
Whether your webhook answered inside that time.
The sample request that was sent to your webhook. It carries `test: true`.
What a real call would do with your webhook's answer.
The HTTP status your webhook returned. Null when it could not be reached.
What went wrong, when `ok` is false. Null otherwise.
curl -X POST "https://api.dialgem.com/v1/phone-numbers/NUMBER_ID/inbound-webhook/test" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"ok": false,
"status_code": 0,
"latency_ms": 0,
"error": "string",
"budget_ms": 0,
"within_budget": false,
"request": {},
"decision": {
"outcome": "string",
"note": "string",
"ignored": {},
"reject_reason": "string",
"agent_id": "agent_123",
"agent_version": null,
"variables": [
"string"
],
"metadata_keys": [
"string"
]
}
}Rotate inbound webhook secret
A new signing secret for the routing webhook, returned once. The old one stops working at once.
Path parameters
Returns
200 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 13 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl -X POST "https://api.dialgem.com/v1/phone-numbers/NUMBER_ID/inbound-webhook/rotate-secret" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}Get phone number by number
Path parameters
Returns
200 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 13 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl "https://api.dialgem.com/v1/phone-numbers/by-number/NUMBER" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}List available numbers
Query parameters
Default "US"
Default "local"
Default 20
Returns
200 with the fields below.
Numbers you can buy, up to the requested limit.
9 properties
The number in E.164 format. Pass it to the buy route.
The number formatted for display.
The kind of number, such as `local` or `toll_free`.
Whether the number can take voice calls.
Whether the number can send and receive text messages.
Whether the number can send and receive picture messages.
City or locality, when the carrier reports one.
State or region, when the carrier reports one.
Two-letter country code.
Monthly rent for this kind of number, in credit units.
Monthly rent for this kind of number, in US dollars.
curl "https://api.dialgem.com/v1/phone-numbers/available" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"numbers": [
{
"phone_number": "+14155550123",
"friendly_name": "string",
"type": "string",
"locality": "string",
"region": "string",
"country": "string",
"voice": false,
"sms": false,
"mms": false
}
],
"monthly_price_units": 0,
"monthly_price_usd": 0
}Buy a phone number
Request body application/json
E.164, as returned by the search
Default "local"
Returns
201 with the fields below.
Dialgem's id for the number. Use it in the `/v1/phone-numbers/{number_id}` routes.
`active` while the number is in use. A released number is no longer listed.
The carrier that holds the number, such as `twilio`.
The number in E.164 format, such as `+14155550100`.
The number formatted for display. Numbers outside the US and Canada are returned unchanged.
Where the number came from, such as `custom` for a number you brought.
Your label for the number. An empty string when none is set.
The version the inbound agent runs: a published version, `0` for the live draft, or `latest_published`.
The version the outbound agent runs: a published version, `0` for the live draft, or `latest_published`.
Weighted routing for inbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Show 15 more parameters
Weighted routing for outbound calls. Empty when no agent is assigned.
3 properties
The agent that takes the call.
The published version to run, `0` for the live draft, or `latest_published` to follow the newest publish.
Relative share of calls sent to this agent. Calls are split in proportion to the weights.
Default 1
Whether the number can send and receive text messages through your own integration.
Whether flow agents may send text messages from this number.
When the number was added, in milliseconds since the Unix epoch.
When the number last changed, in milliseconds since the Unix epoch.
Monthly rent in credit units, charged to your balance.
Monthly rent in US dollars.
The agent that answers calls to this number. Null when none is assigned.
The agent that places calls from this number. Null when none is assigned.
Outbound SIP trunk settings. Null when the number has none.
3 properties
The SIP address calls from this number are sent to.
SIP transport, such as `TCP`, `UDP` or `TLS`.
Username the trunk authenticates with. The password is never returned here.
A URL asked how to handle each inbound call before it is answered. Null when not set.
The last four characters of the webhook signing secret, so you can tell secrets apart. Null when no webhook is set.
The signing secret for the inbound webhook. Present only in the response that creates or rotates it, and shown that once. Store it then.
The SIP password for the number's outbound trunk, or an empty string when none is set. Present only when looking a number up by its phone number.
True when the number belongs to your own connected Twilio account. Present only when looking a number up by its phone number.
curl -X POST "https://api.dialgem.com/v1/phone-numbers/buy" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155550123"
}'{
"id": "string",
"status": "string",
"provider": "string",
"phone_number": "+14155550123",
"phone_number_pretty": "string",
"phone_number_type": "string",
"nickname": "string",
"inbound_agent_id": "inbound_agent_123",
"inbound_agent_version": 0,
"outbound_agent_id": "outbound_agent_123",
"outbound_agent_version": 0,
"inbound_agents": [
{
"agent_id": "agent_123",
"agent_version": 0,
"weight": 1
}
]
}