Skip to navigation
Compatibility REST APIIncoming Phone Numbers

Create an Incoming Phone Number

View as MarkdownOpen in Claude

Purchases an available number and provisions it as an Incoming Phone Number in the account. Search first with Available Phone Numbers, or use SignalWire REST Purchase phone number for a JSON request. To register a number you already own instead of purchasing inventory, use Imported Phone Numbers.

Purchasing a number starts a release hold, so you can’t release it right away. For most Spaces the hold lasts 14 days, with up to 2 early releases each month. See Delete an incoming phone number.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.

Learn more about API scopes.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Path parameters

AccountSidstringRequiredformat: "uuid"
The unique identifier for the account that is associated with this phone number.

Request

This endpoint expects an object.
PhoneNumberstringRequiredformat: "^\+\d{5,17}$"6-18 characters

The phone number to purchase in E.164 format. Must start with + followed by 5-17 digits.

FriendlyNamestringOptional
A friendly name for the phone number. If not provided, the formatted phone number will be used.
SmsApplicationSidstringOptionalformat: "uuid"
The unique identifier for the application associated with SMS handling on this phone number.
SmsFallbackMethodenumOptionalDefaults to POST

Whether the request to SmsFallbackUrl is a GET or a POST. Default is POST.

Allowed values:
SmsFallbackUrlstringOptionalformat: "uri"
The URL to request if errors occur when fetching SmsUrl.
SmsMethodenumOptionalDefaults to POST

Whether the request to SmsUrl is a GET or a POST. Default is POST.

Allowed values:
SmsUrlstringOptionalformat: "uri"
The URL to request when an incoming SMS is received.
StatusCallbackstringOptionalformat: "uri"

The URL to request to pass status updates to. See the Incoming call status callback webhook for the payload your URL will receive.

StatusCallbackMethodenumOptionalDefaults to POST

Whether the request to StatusCallback is a GET or a POST. Default is POST.

Allowed values:
VoiceApplicationSidstringOptionalformat: "uuid"
The unique identifier for the application associated with call handling on this phone number.
VoiceFallbackMethodenumOptionalDefaults to POST

Whether the request to VoiceFallbackUrl is a GET or a POST. Default is POST.

Allowed values:
VoiceFallbackUrlstringOptionalformat: "uri"
The URL to request if errors occur when fetching VoiceUrl.
VoiceMethodenumOptionalDefaults to POST

Whether the request to VoiceUrl is a GET or a POST. Default is POST.

Allowed values:
VoiceReceiveModeenumOptionalDefaults to voice

Whether this number can receive voice calls or faxes. Default is voice.

Allowed values:
VoiceUrlstringOptionalformat: "uri"
The URL to request when an incoming call is received.

Response

Response returned when an incoming phone number is created.
account_idstringformat: "uuid"
The unique identifier for the account that is associated with this phone number.
account_sidstringformat: "uuid"
The unique identifier for the account that is associated with this phone number.
address_requirementsenum
Whether or not a registered address with SignalWire is required. Always 'none'.
Allowed values:
address_sidstring or null
The unique identifier for the address associated with this phone number. Always null.
api_versionstring
The version of the SignalWire API.
betaboolean
New numbers on SignalWire are marked as beta. Always false.
call_handlerstring

How incoming calls to this number are handled. laml_webhooks sends calls to voice_url, and laml_application sends them to the application in voice_application_sid. Any other value means the number’s call handler was set outside the Compatibility API.

This field is read-only in the Compatibility API. Setting VoiceUrl or VoiceApplicationSid switches the number to laml_webhooks or laml_application; to choose any other handler, use Update phone number.

capabilitiesobject
Whether or not a number can receive calls and messages.
country_codestring

The ISO 3166-1 alpha-2 country code for this phone number.

date_createdstring
The date, in RFC 2822 format, this phone number was created.
date_updatedstring
The date, in RFC 2822 format, this phone number was updated.
emergency_address_sidstring or null
The unique identifier of the address associated with E911 for this phone number, or null if not set.
emergency_statusstring
Whether the phone route has an active E911 address associated. 'Active' or 'Inactive'.
friendly_namestring
A formatted version of the number.
identity_sidstring or null
The unique identifier for the identity associated with this phone number. Always null.
originenum
The origin of the phone number.
Allowed values:
pending_port_inboolean

Whether the number is part of a port-in that hasn’t completed. A number pending port-in can’t be assigned to a 10DLC campaign.

phone_numberstring
The incoming number in E.164 format.
sidstring
The unique identifier for this phone number.
sms_application_sidstring or null
The unique identifier for the application associated with SMS handling on this phone number, or null if not set.
sms_fallback_methodstring

Whether the request to SmsFallbackUrl is a GET or a POST.

sms_fallback_urlstring or null
The URL to request if errors occur when fetching SmsUrl, or null if not set.
sms_methodstring

Whether the request to SmsUrl is a GET or a POST.

sms_urlstring or null
The URL to request when an incoming SMS is received, or null if not set.
status_callbackstring or null
The URL to request to pass status updates to, or null if not set.
status_callback_methodstring

Whether the request to StatusCallback is a GET or a POST.

trunk_sidstring or null
The unique identifier for the Trunk associated with this phone number. Always null.
uristring
The URI for this number.
voice_application_sidstring or null
The unique identifier for the application associated with call handling on this phone number, or null if not set.
voice_caller_id_lookupboolean or null
Whether or not to look up a caller's name in the database. Always null.
voice_fallback_methodstring

Whether the request to VoiceFallbackUrl is a GET or a POST.

voice_fallback_urlstring or null

The URL to request if errors occur when fetching Url, or null if not set.

voice_methodstring

Whether the request to Url is a GET or a POST.

voice_urlstring or null
The URL to request when an incoming call is received, or null if not set.
verification_statusstringOptional

The verification status for toll-free numbers. Only present for toll-free numbers.

Errors

400
Bad Request Error
422
Unprocessable Entity Error