telephony.phoneNumbers.create

Add a number and point it at an agent.

Set inbound_workflow_id to bind incoming calls on this number to a specific agent — Decibyl will register the inbound webhook with the provider and the response will include a provider_sync block reporting the result. Omit it to add the number for outbound use only.

The (provider, account_id, address) tuple must be globally unique across all Decibyl organizations, since inbound dispatch keys on it. Attempting to add a number that another organization already owns returns 409.

Reference

POST/api/v1/organizations/telephony-configs/{config_id}/phone-numbers

Auth

API key in X-API-Key

Content

application/json

Returns

200 · PhoneNumberResponse

Arguments

Argument	In	Type	Required	Description
config_id	path	integer	required
address	body	string	required
country_code	body	string	optional
label	body	string	optional
inbound_workflow_id	body	integer	optional
callback_workflow_id	body	integer	optional
is_active	body	boolean	default true
is_default_caller_id	body	boolean	default false
extra_metadata	body	Extra Metadata	optional

Example request

curl -X POST "https://api.decibyl.ai/api/v1/organizations/telephony-configs/<config_id>/phone-numbers" \
  -H "X-API-Key: dcb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"address":"string","country_code":"string","label":"string","inbound_workflow_id":1,"callback_workflow_id":1,"is_active":true,"is_default_caller_id":false,"extra_metadata":{}}'

Response

{
  "id": 1,
  "telephony_configuration_id": 1,
  "address": "string",
  "address_normalized": "string",
  "address_type": "string",
  "country_code": "string",
  "label": "string",
  "inbound_workflow_id": 1,
  "inbound_workflow_name": "string",
  "callback_workflow_id": 1,
  "inbound_contact_list_id": 1,
  "inbound_require_known_caller": false,
  "inbound_max_calls_per_caller": 1,
  "inbound_call_window_hours": 24,
  "inbound_allow_list": [
    "string"
  ],
  "is_active": true,
  "is_default_caller_id": true,
  "extra_metadata": {},
  "created_at": "2026-09-14T09:30:00Z",
  "updated_at": "2026-09-14T09:30:00Z",
  "status": "active",
  "carrier_number_id": "string",
  "provisioned_at": "2026-09-14T09:30:00Z",
  "released_at": "2026-09-14T09:30:00Z",
  "provider_sync": {
    "ok": true,
    "message": "string"
  },
  "predeclaration_status": "string"
}

Errors

Status	When
404	Not found
422	Validation Error