Incoming Phone Numbers

Create an Incoming Phone Number

Changed on

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.

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.

post/Accounts/{AccountSid}/IncomingPhoneNumbers

Request

  • Base URL
    https://YOUR_SPACE.signalwire.com/api/laml/2010-04-01
  • URL
    https://YOUR_SPACE.signalwire.com/api/laml/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers
  • Auth
    HTTP basic

Path parameters

AccountSidstring uuid required

Universal Unique Identifier.

The unique identifier for the account that is associated with this phone number.

Request body application/x-www-form-urlencoded

PhoneNumberstring required

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

FriendlyNamestring

A friendly name for the phone number. If not provided, the formatted phone number will be used.

SmsApplicationSidstring uuid

Universal Unique Identifier.

SmsFallbackMethod'GET' | 'POST'

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

SmsFallbackUrlstring uri

The URL to request if errors occur when fetching SmsUrl.

SmsMethod'GET' | 'POST'

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

SmsUrlstring uri

The URL to request when an incoming SMS is received.

StatusCallbackstring uri

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

StatusCallbackMethod'GET' | 'POST'

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

VoiceApplicationSidstring uuid

Universal Unique Identifier.

VoiceFallbackMethod'GET' | 'POST'

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

VoiceFallbackUrlstring uri

The URL to request if errors occur when fetching VoiceUrl.

VoiceMethod'GET' | 'POST'

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

VoiceReceiveMode'voice' | 'fax'

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

VoiceUrlstring uri

The URL to request when an incoming call is received.

Example request

{
  "PhoneNumber": "+13103386745",
  "FriendlyName": "My Business Line",
  "SmsFallbackMethod": "POST",
  "SmsFallbackUrl": "https://example.com/sms-fallback",
  "SmsMethod": "POST",
  "SmsUrl": "https://example.com/sms",
  "StatusCallback": "https://example.com/status",
  "StatusCallbackMethod": "POST",
  "VoiceFallbackMethod": "POST",
  "VoiceFallbackUrl": "https://example.com/voice-fallback",
  "VoiceMethod": "POST",
  "VoiceReceiveMode": "voice",
  "VoiceUrl": "https://example.com/voice"
}

Response

Response returned when an incoming phone number is created.

account_idstring uuid required

Universal Unique Identifier.

account_sidstring uuid required

Universal Unique Identifier.

address_requirements'none' | 'any' | 'local' | 'foreign' required

Address requirements.

address_sidstring nullable required

The unique identifier for the address associated with this phone number. Always null.

api_versionstring required

The version of the SignalWire API.

betaboolean required

New numbers on SignalWire are marked as beta. Always false.

country_codestring required

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

date_createdstring required

The date, in RFC 2822 format, this phone number was created.

date_updatedstring required

The date, in RFC 2822 format, this phone number was updated.

emergency_address_sidstring nullable required

The unique identifier of the address associated with E911 for this phone number, or null if not set.

emergency_statusstring required

Whether the phone route has an active E911 address associated. 'Active' or 'Inactive'.

friendly_namestring required

A formatted version of the number.

identity_sidstring nullable required

The unique identifier for the identity associated with this phone number. Always null.

origin'signalwire' | 'hosted' required

Phone number origin.

phone_numberstring required

The incoming number in E.164 format.

sidstring required

The unique identifier for this phone number.

sms_application_sidstring nullable required

The unique identifier for the application associated with SMS handling on this phone number, or null if not set.

sms_fallback_methodstring required

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

sms_fallback_urlstring nullable required

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

sms_methodstring required

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

sms_urlstring nullable required

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

status_callbackstring nullable required

The URL to request to pass status updates to, or null if not set.

status_callback_methodstring required

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

trunk_sidstring nullable required

The unique identifier for the Trunk associated with this phone number. Always null.

uristring required

The URI for this number.

verification_statusstring

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

voice_application_sidstring nullable required

The unique identifier for the application associated with call handling on this phone number, or null if not set.

voice_caller_id_lookupboolean nullable required

Whether or not to look up a caller's name in the database. Always null.

voice_fallback_methodstring required

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

voice_fallback_urlstring nullable required

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

voice_methodstring required

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

voice_urlstring nullable required

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

Example response

{
  "api_version": "2010-04-01",
  "capabilities": {
    "voice": true,
    "sms": true,
    "mms": true,
    "fax": true
  },
  "country_code": "US",
  "date_created": "Tue, 25 Sept 2018 23:00:00 +0000",
  "date_updated": "Wed, 26 Sept 2018 22:00:00 +0000",
  "emergency_status": "Inactive",
  "friendly_name": "(310) 338-6745",
  "phone_number": "+13103386745",
  "sid": "b3877c40-da60-4998-90ad-b792e98472pn",
  "sms_fallback_method": "POST",
  "sms_method": "POST",
  "status_callback_method": "POST",
  "uri": "/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472ac/IncomingPhoneNumbers/b3877c40-da60-4998-90ad-b792e98472pn.json",
  "verification_status": "Unverified",
  "voice_fallback_method": "POST",
  "voice_method": "POST"
}

Changes

  • 2916d5e3072eRevision changes
    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      the response's property type changed from string to no type, and format from uuid to no format for status

    • breaking

      the response's property type changed from string to no type, and format from uuid to no format for status

    • info

      the request property type was generalized from string to no type, and format from uuid to no format

    • info

      the request property type was generalized from string to no type, and format from uuid to no format

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

  • 5344c0c93a4cRevision changes
    • breaking

      added 'unevaluatedProperties' constraint to the request body

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the //// response property for the status