Skip to navigation
Compatibility REST APIImported Phone Numbers

Import a Phone Number

View as MarkdownOpen in Claude

Registers a phone number you already own so it can route communications through the project while remaining externally hosted. Use Create an Incoming Phone Number to purchase from SignalWire inventory, or SignalWire REST Import phone number for a JSON request.

Note: This is a Partner API. To enable it on your SignalWire Space, contact Sales.

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.
numberstringRequiredformat: "^\+\d{5,30}$"6-31 characters

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

number_typeenumRequired
The type of phone number being imported.
Allowed values:
capabilitieslist of enumsOptional

The capabilities to enable for this phone number. If not provided, defaults to all capabilities (sms, voice, fax, mms). If provided, must include at least one capability.

Allowed values:

Response

The request has succeeded and a new resource has been created as a result.
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