Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Incoming Phone Numbers

An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio, ported or hosted to Twilio.

The IncomingPhoneNumbers list resource represents an account's Twilio phone numbers. You can POST to the list resource to provision a new Twilio number. To find a new number to provision use the subresources of the AvailablePhoneNumbers resource.

You can transfer phone numbers between two Twilio accounts if you're using subaccounts. For details, see Exchanging Numbers Between Subaccounts.

Provisioning a phone number is a two-step process. First, you must find an available phone number to provision using the subresources of the AvailablePhoneNumbers resource. Second, you must POST to the IncomingPhoneNumbers list resource, documented below.

IncomingPhoneNumber Properties

Each instance of an IncomingPhoneNumber resource has the following properties:

account_sid
sid<AC> Not PII

The unique id of the Account responsible for this phone number.

address_requirements
enum:address_requirement Not PII

This indicates whether the phone number requires you or your customer to have an Address registered with Twilio. Possible values are none, any, local, or foreign.

address_sid
sid<AD> Not PII

The 34 character sid of the address Twilio should use to associate with the number. Addresses are required in some regions to meet local regulations

api_version
string Not PII

Calls to this phone number will start a new TwiML session with this API version.

beta
boolean Not PII

Phone numbers new to the Twilio platform are marked as beta. Possible values are either true or false.

capabilities
phone_number_capabilities Not PII

This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, and MMS with each having a value of either true or false.

date_created
date_time<rfc2822> Not PII

The date that this resource was created, given as GMT RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date that this resource was last updated, given as GMT RFC 2822 format.

friendly_name

A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number.

identity_sid
sid<RI> Not PII

The 34 character sid of the identity Twilio should use to associate with the number. Identities are required in some regions to meet local regulations

origin
string Not PII

Twilio owned phone numbers are marked as twilio while hosted phone numbers are marked as hosted.

phone_number
phone_number Not PII

The incoming phone number. e.g., +16175551212 (E.164 format)

sid
sid<PN> Not PII

A 34 character string that uniquely identifies this resource.

sms_application_sid
sid<AP> Not PII

The 34 character sid of the application Twilio should use to handle SMSs sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.

sms_fallback_method
http_method Not PII

The HTTP method Twilio will use when requesting the above URL. Either GET or POST.

sms_fallback_url
url Not PII

The URL that Twilio will request if an error occurs retrieving or executing the TwiML from SmsUrl.

sms_method
http_method Not PII

The HTTP method Twilio will use when making requests to the SmsUrl. Either GET or POST.

sms_url
url Not PII

The URL Twilio will request when receiving an incoming SMS message to this number.

status_callback
url Not PII

The URL that Twilio will request to pass status parameters (such as call ended) to your application.

status_callback_method
http_method Not PII

The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.

trunk_sid
sid<TR> Not PII

The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.

uri
uri Not PII

The URI for this resource, relative to https://api.twilio.com.

voice_application_sid
sid<AP> Not PII

The 34 character sid of the application Twilio should use to handle phone calls to this number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.

voice_caller_id_lookup
boolean Not PII

Look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Either true or false.

voice_fallback_method
http_method Not PII

The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.

voice_fallback_url
url Not PII

The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by Url.

voice_method
http_method Not PII

The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

voice_url
url Not PII

The URL Twilio will request when this phone number receives a call. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.

Address Requirement Values

The following are the possible values for the address_required property.

Status Description
none An Address is not required for this phone number.
any Your account must have an Address, but it can be anywhere in the world.
local Your account must have an Address within the phone number's country.
foreign Your account must have an Address outside the phone number's country.
POST
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers

Purchases a new phone number for your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio cannot find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.

If the number you are trying to purchase has address requirements, the system will look for an address on your account that satisfies the requirement. If you have multiple addresses, you can specify which address to associate with the number by passing the optional AddressSid parameter.

If the number you are trying to purchase requires an identity document on file and you don’t have a verified identity document associated with your account, you will receive an HTTP 400 with Twilio error code 21650. See this support article for more details.

To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Please note: You cannot request numbers via the API while you are using a Free Trial account. You must upgrade your account to purchase a Twilio phone number programmatically.

Parameters

Your request may include the following parameters:

AccountSid
Required
post sid<AC> Not PII

The unique id of the Account responsible for this phone number.

AreaCode
Required if PhoneNumber is not passed
post string Not PII

The desired area code for your new incoming phone number. Any three digit, US or Canada area code is valid. Twilio will provision a random phone number within this area code for you. You must include either this or a PhoneNumber parameter to have your POST succeed. (US and Canada only)

PhoneNumber
Required if AreaCode is not passed
post phone_number Not PII

The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include either this or an AreaCode parameter to have your POST succeed.

AddressSid
Optional
post sid<AD> Not PII

The 34 character sid of the address Twilio should use to associate with the number. Addresses are required in some regions to meet local regulations

ApiVersion
Optional
post string Not PII

The Twilio REST API version to use for incoming calls made to this number. If omitted, uses 2010-04-01.

EmergencyAddressSid
Optional
post sid<AD> Not PII

The 34 character sid of the EmergencyAddress configuration to leverage emergency calling for this phone number

EmergencyStatus
Optional
post enum:emergency_status Not PII

The configuration status parameter determining whether this phone number is enabled for emergency calling

FriendlyName
Optional
post string Not PII

A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number.

IdentitySid
Optional
post sid<RI> Not PII

The 34 character sid of the identity Twilio should use to associate with the number. Identities are required in some regions to meet local regulations

SmsApplicationSid
Optional
post sid<AP> Not PII

The 34 character sid of the application Twilio should use to handle SMSs sent to the new number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.

SmsFallbackMethod
Optional
post http_method Not PII

The HTTP method that should be used to request the SmsFallbackUrl. Must be either GET or POST. Defaults to POST.

SmsFallbackUrl
Optional
post url Not PII

A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.

SmsMethod
Optional
post http_method Not PII

The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.

SmsUrl
Optional
post url Not PII

The URL Twilio will request when receiving an incoming SMS message to this number.

StatusCallback
Optional
post url Not PII

The URL that Twilio will request to pass status parameters (such as call ended) to your application.

StatusCallbackMethod
Optional
post http_method Not PII

The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST. Defaults to POST.

TrunkSid
Optional
post sid<TR> Not PII

The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.

VoiceApplicationSid
Optional
post sid<AP> Not PII

The 34 character sid of the application Twilio should use to handle phone calls to the new number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.

VoiceCallerIdLookup
Optional
post boolean Not PII

Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. Defaults to false.

VoiceFallbackMethod
Optional
post http_method Not PII

The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST. Defaults to POST.

VoiceFallbackUrl
Optional
post url Not PII

The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by Url.

VoiceMethod
Optional
post http_method Not PII

The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.

VoiceReceiveMode
Optional
post ienum:voice_receive_mode Not PII

The configuration parameter for this phone number to receive incoming voice calls or faxes. Must be either fax or voice. Defaults to voice

VoiceUrl
Optional
post url Not PII

The URL that Twilio should request when somebody dials the new phone number. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.

If successful, Twilio responds with a representation of the new phone number that was assigned to your account.

Example
Loading Code Sample...
      
      
      
      
      GET
      https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}
      Loading Code Sample...
          
          
          
          
          GET
          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers

          Returns a list of IncomingPhoneNumber resource representations, each representing a phone number given to your account. The list includes paging information.

          List Filters

          The following query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

          AccountSid
          Required
          get sid<AC> Not PII

          The unique id of the Account responsible for this phone number.

          Beta
          Optional
          get boolean Not PII

          Include phone numbers new to the Twilio platform. Possible values are either true or false. Default is true.

          FriendlyName
          Optional
          get string Not PII

          Only show the incoming phone number resources with friendly names that exactly match this name.

          Origin
          Optional
          get string Not PII

          Include phone numbers based on the origin, by default, phone numbers of all origin are included. Possible values are either twilio or hosted.

          PhoneNumber
          Optional
          get phone_number Not PII

          Only show the incoming phone number resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit.

          Loading Code Sample...
              
              
              
              
              Example 2

              Return the set of phone numbers that match exactly (415) 867-5309.

              Loading Code Sample...
                  
                  
                  
                  
                  Example 3

                  Return the set of all phone numbers containing the digits 867.

                  Loading Code Sample...
                      
                      
                      
                      
                      POST
                      https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

                      Tries to update the incoming phone number's properties, and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

                      Parameters

                      You may specify one or more of the following parameters to update this phone number's respective properties:

                      AccountSid
                      Required
                      post sid<AC> Not PII

                      The unique 34 character id of the account to which you wish to transfer this phone number. See Exchanging Numbers Between Subaccounts.

                      AddressSid
                      Optional
                      post sid<AD> Not PII

                      The 34 character sid of the address Twilio should associate with the number. If the number has address restrictions, only another address that satisfies the requirement can replace the existing one.

                      ApiVersion
                      Optional
                      post string Not PII

                      Calls to this phone number will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01.

                      EmergencyAddressSid
                      Optional
                      post sid<AD> Not PII

                      The 34 character sid of the EmergencyAddress configuration to leverage emergency calling for this phone number

                      EmergencyStatus
                      Optional
                      post enum:emergency_status Not PII

                      The configuration status parameter determining whether this phone number is enabled for emergency calling

                      FriendlyName
                      Optional
                      post string Not PII

                      A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number.

                      IdentitySid
                      Optional
                      post sid<RI> Not PII

                      The 34 character sid of the identity Twilio should use to associate with the number. Identities are required in some regions to meet local regulations

                      SmsApplicationSid
                      Optional
                      post sid<AP> Not PII

                      The 34 character sid of the application Twilio should use to handle SMSs sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application instead.

                      SmsFallbackMethod
                      Optional
                      post http_method Not PII

                      The HTTP method that should be used to request the SmsFallbackUrl. Either GET or POST.

                      SmsFallbackUrl
                      Optional
                      post url Not PII

                      A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.

                      SmsMethod
                      Optional
                      post http_method Not PII

                      The HTTP method Twilio will use when making requests to the SmsUrl. Either GET or POST.

                      SmsUrl
                      Optional
                      post url Not PII

                      The URL that Twilio should request when somebody sends an SMS to the new phone number.

                      StatusCallback
                      Optional
                      post url Not PII

                      The URL that Twilio will request to pass status parameters (such as call ended) to your application.

                      StatusCallbackMethod
                      Optional
                      post http_method Not PII

                      The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.

                      TrunkSid
                      Optional
                      post sid<TR> Not PII

                      The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.

                      VoiceApplicationSid
                      Optional
                      post sid<AP> Not PII

                      The 34 character sid of the application Twilio should use to handle phone calls to this number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application instead. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.

                      VoiceCallerIdLookup
                      Optional
                      post boolean Not PII

                      Look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Either true or false.

                      VoiceFallbackMethod
                      Optional
                      post http_method Not PII

                      The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.

                      VoiceFallbackUrl
                      Optional
                      post url Not PII

                      A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by VoiceUrl.

                      VoiceMethod
                      Optional
                      post http_method Not PII

                      The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

                      VoiceReceiveMode
                      Optional
                      post enum:voice_receive_mode Not PII

                      The configuration parameter for this phone number to receive incoming voice calls or faxes. Must be either fax or voice. Defaults to voice

                      VoiceUrl
                      Optional
                      post url Not PII

                      The URL that Twilio should request when somebody dials the phone number. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.

                      Example 1

                      Set the VoiceUrl and SmsUrl on a phone number

                      Loading Code Sample...
                          
                          
                          
                          
                          DELETE
                          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

                          Release this phone number from your account. Twilio will no longer answer calls to this number, and you will stop being billed the monthly phone number fee. The phone number will eventually be recycled and potentially given to another customer, so use with care. If you make a mistake, contact us. We may be able to give you the number back.

                          If successful, returns an HTTP 204 response with no body.

                          Example 1

                          Release a phone number from your account.

                          Loading Code Sample...
                              
                              
                              
                              

                              Need some help?

                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                              Loading Code Sample...