Menu

Expand
Rate this page:

IncomingPhoneNumber resource

An IncomingPhoneNumber instance resource represents a Twilio phone number provisioned 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

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created this IncomingPhoneNumber resource.

address_sid
sid<AD> Not PII

The SID of the Address resource associated with the phone number.

address_requirements
enum:address_requirement Not PII

Whether the phone number requires an Address registered with Twilio. Can be: none, any, local, or foreign.

api_version
string Not PII

The API version used to start a new TwiML session.

beta
boolean Not PII

Whether the phone number is new to the Twilio platform. Can be: true or false.

capabilities
phone_number_capabilities Not PII

The set of Boolean properties that indicate whether a phone number can receive calls or messages. Capabilities are Voice, SMS, and MMS and each capability can be: true or false.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

friendly_name

The string that you assigned to describe the resource.

identity_sid
sid<RI> Not PII

The SID of the Identity resource that we associate with the phone number. Some regions require an Identity to meet local regulations.

phone_number
phone_number Not PII

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.

origin
string Not PII

The phone number's origin. twilio identifies Twilio-owned phone numbers and hosted identifies hosted phone numbers.

sid
sid<PN> Not PII

The unique string that that we created to identify this IncomingPhoneNumber resource.

sms_application_sid
sid<AP> Not PII

The SID of the application that handles SMS messages sent to the phone number. If an sms_application_sid is present, we ignore all sms_*_url values and use those of the application.

sms_fallback_method
http_method Not PII

The HTTP method we use to call sms_fallback_url. Can be: GET or POST.

sms_fallback_url
url Not PII

The URL that we call when an error occurs while retrieving or executing the TwiML from sms_url.

sms_method
http_method Not PII

The HTTP method we use to call sms_url. Can be: GET or POST.

sms_url
url Not PII

The URL we call when the phone number receives an incoming SMS message.

status_callback
url Not PII

The URL we call using the status_callback_method to send status information to your application.

status_callback_method
http_method Not PII

The HTTP method we use to call status_callback. Can be: GET or POST.

trunk_sid
sid<TK> Not PII

The SID of the Trunk that handles calls to the phone number. If a trunk_sid is present, we ignore all of the voice urls and voice applications and use those set on the Trunk. Setting a trunk_sid will automatically delete your voice_application_sid and vice versa.

uri
uri Not PII

The URI of the resource, relative to https://api.twilio.com.

voice_receive_mode
enum:voice_receive_mode Not PII

voice_application_sid
sid<AP> Not PII

The SID of the application that handles calls to the phone number. If a voice_application_sid is present, we ignore all of the voice urls and use those set on the application. Setting a voice_application_sid will automatically delete your trunk_sid and vice versa.

voice_caller_id_lookup
boolean Not PII

Whether we look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Can be: true or false.

voice_fallback_method
http_method Not PII

The HTTP method we use to call voice_fallback_url. Can be: GET or POST.

voice_fallback_url
url Not PII

The URL that we call when an error occurs retrieving or executing the TwiML requested by url.

voice_method
http_method Not PII

The HTTP method we use to call voice_url. Can be: GET or POST.

voice_url
url Not PII

The URL we call when the phone number receives a call. The voice_url will not be used if a voice_application_sid or a trunk_sid is set.

emergency_status
enum:emergency_status Not PII

The configuration status parameter that determines whether the phone number is enabled for emergency calling.

emergency_address_sid
sid<AD> Not PII

The SID of the emergency address configuration that we use for emergency calling from this phone number.

bundle_sid
sid<BU> Not PII

The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

status
string Not PII

Create an IncomingPhoneNumber resource

post
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
Parameters
Parameters in REST API format
account_sid
Path
post sid<AC> Not PII

The SID of the Account that will create the resource.

api_version
Optional
post string Not PII

The API version to use for incoming calls made to the new phone number. The default is 2010-04-01.

friendly_name
Optional
post string PII MTL: 30 DAYS

A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.

sms_application_sid
Optional
post sid<AP> Not PII

The SID of the application that should handle SMS messages sent to the new phone number. If an sms_application_sid is present, we ignore all of the sms_*_url urls and use those set on the application.

sms_fallback_method
Optional
post http_method Not PII

The HTTP method that we should use to call sms_fallback_url. Can be: GET or POST and defaults to POST.

sms_fallback_url
Optional
post url Not PII

The URL that we should call when an error occurs while requesting or executing the TwiML defined by sms_url.

sms_method
Optional
post http_method Not PII

The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.

sms_url
Optional
post url Not PII

The URL we should call when the new phone number receives an incoming SMS message.

status_callback
Optional
post url Not PII

The URL we should call using the status_callback_method to send status information to your application.

status_callback_method
Optional
post http_method Not PII

The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

voice_application_sid
Optional
post sid<AP> Not PII

The SID of the application we should use to handle calls to the new phone number. If a voice_application_sid is present, we ignore all of the voice urls and use only those set on the application. Setting a voice_application_sid will automatically delete your trunk_sid and vice versa.

voice_caller_id_lookup
Optional
post boolean Not PII

Whether to lookup the caller's name from the CNAM database and post it to your app. Can be: true or false and defaults to false.

voice_fallback_method
Optional
post http_method Not PII

The HTTP method that we should use to call voice_fallback_url. Can be: GET or POST and defaults to POST.

voice_fallback_url
Optional
post url Not PII

The URL that we should call when an error occurs retrieving or executing the TwiML requested by url.

voice_method
Optional
post http_method Not PII

The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.

voice_url
Optional
post url Not PII

The URL that we should call to answer a call to the new phone number. The voice_url will not be called if a voice_application_sid or a trunk_sid is set.

emergency_status
Optional
post enum:emergency_status Not PII

The configuration status parameter that determines whether the new phone number is enabled for emergency calling.

emergency_address_sid
Optional
post sid<AD> Not PII

The SID of the emergency address configuration to use for emergency calling from the new phone number.

trunk_sid
Optional
post sid<TK> Not PII

The SID of the Trunk we should use to handle calls to the new phone number. If a trunk_sid is present, we ignore all of the voice urls and voice applications and use only those set on the Trunk. Setting a trunk_sid will automatically delete your voice_application_sid and vice versa.

identity_sid
Optional
post sid<RI> Not PII

The SID of the Identity resource that we should associate with the new phone number. Some regions require an identity to meet local regulations.

address_sid
Optional
post sid<AD> Not PII

The SID of the Address resource we should associate with the new phone number. Some regions require addresses to meet local regulations.

voice_receive_mode
Optional
post ienum:voice_receive_mode Not PII

The configuration parameter for the new phone number to receive incoming voice calls or faxes. Can be: fax or voice and defaults to voice.

bundle_sid
Optional
post sid<BU> Not PII

The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

phone_number
Required if area_code is not passed
post phone_number Not PII

The phone number to purchase specified in E.164 format. E.164 phone numbers consist of a + followed by the country code and subscriber number without punctuation characters. For example, +14155551234.

area_code
Required if phone_number is not passed
post string Not PII

The desired area code for your new incoming phone number. Can be any three-digit, US or Canada area code. We will provision an available phone number within this area code for you. You must provide an area_code or a phone_number. (US and Canada only).

Example 1
        
        
        
        You will be charged when you provision the number, and the number will appear on the Numbers page in the console.

        Provision a Phone Number

        You will be charged when you provision the number, and the number will appear on the Numbers page in the console.
        Example 2
              
              
              
              Provide an AddressSid and a BundleSid for your new IncomingPhoneNumber

              Provision a Phone Number with an AddressSid and a BundleSid

              Provide an AddressSid and a BundleSid for your new IncomingPhoneNumber
              Example 3
                    
                    
                    
                    Twilio will send a HTTP request to this URL when a call comes in to your phone number

                    Provision a Phone Number with a Voice URL

                    Twilio will send a HTTP request to this URL when a call comes in to your phone number
                    Example 4
                          
                          
                          
                          Twilio will send a HTTP request to this URL when an SMS is sent to your phone number

                          Provision a Phone Number with an SMS URL

                          Twilio will send a HTTP request to this URL when an SMS is sent to your phone number

                          Fetch an IncomingPhoneNumber resource

                          get
                          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json
                          Parameters
                          Parameters in REST API format
                          account_sid
                          Path
                          get sid<AC> Not PII

                          The SID of the Account that created the IncomingPhoneNumber resource to fetch.

                          sid
                          Path
                          get sid<PN> Not PII

                          The Twilio-provided string that uniquely identifies the IncomingPhoneNumber resource to fetch.

                          Example 1
                                
                                
                                

                                Read multiple IncomingPhoneNumber resources

                                get
                                https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
                                Parameters
                                Parameters in REST API format
                                account_sid
                                Path
                                get sid<AC> Not PII

                                The SID of the Account that created the IncomingPhoneNumber resources to read.

                                beta
                                Optional
                                get boolean Not PII

                                Whether to include phone numbers new to the Twilio platform. Can be: true or false and the default is true.

                                friendly_name
                                Optional
                                get string PII MTL: 30 DAYS

                                A string that identifies the IncomingPhoneNumber resources to read.

                                phone_number
                                Optional
                                get phone_number Not PII

                                The phone numbers of the IncomingPhoneNumber resources to read. You can specify partial numbers and use '*' as a wildcard for any digit.

                                origin
                                Optional
                                get string Not PII

                                Whether to include phone numbers based on their origin. Can be: twilio or hosted. By default, phone numbers of all origin are included.

                                Example 1
                                      
                                      
                                      
                                      Example 2
                                            
                                            
                                            
                                            Return the set of phone numbers that match exactly (415) 867-5310

                                            Filter IncomingPhoneNumbers with exact match

                                            Return the set of phone numbers that match exactly (415) 867-5310
                                            Example 3
                                                  
                                                  
                                                  
                                                  Return the set of all phone numbers containing the digits 867

                                                  Filter IncomingPhoneNumbers with partial match

                                                  Return the set of all phone numbers containing the digits 867

                                                  Update an IncomingPhoneNumber resource

                                                  post
                                                  https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json
                                                  Parameters
                                                  Parameters in REST API format
                                                  account_sid
                                                  Optional
                                                  post sid<AC> Not PII

                                                  The SID of the Account that created the IncomingPhoneNumber resource to update. For more information, see Exchanging Numbers Between Subaccounts.

                                                  sid
                                                  Path
                                                  post sid<PN> Not PII

                                                  The Twilio-provided string that uniquely identifies the IncomingPhoneNumber resource to update.

                                                  api_version
                                                  Optional
                                                  post string Not PII

                                                  The API version to use for incoming calls made to the phone number. The default is 2010-04-01.

                                                  friendly_name
                                                  Optional
                                                  post string PII MTL: 30 DAYS

                                                  A descriptive string that you created to describe this phone number. It can be up to 64 characters long. By default, this is a formatted version of the phone number.

                                                  sms_application_sid
                                                  Optional
                                                  post sid<AP> Not PII

                                                  The SID of the application that should handle SMS messages sent to the number. If an sms_application_sid is present, we ignore all of the sms_*_url urls and use those set on the application.

                                                  sms_fallback_method
                                                  Optional
                                                  post http_method Not PII

                                                  The HTTP method that we should use to call sms_fallback_url. Can be: GET or POST and defaults to POST.

                                                  sms_fallback_url
                                                  Optional
                                                  post url Not PII

                                                  The URL that we should call when an error occurs while requesting or executing the TwiML defined by sms_url.

                                                  sms_method
                                                  Optional
                                                  post http_method Not PII

                                                  The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.

                                                  sms_url
                                                  Optional
                                                  post url Not PII

                                                  The URL we should call when the phone number receives an incoming SMS message.

                                                  status_callback
                                                  Optional
                                                  post url Not PII

                                                  The URL we should call using the status_callback_method to send status information to your application.

                                                  status_callback_method
                                                  Optional
                                                  post http_method Not PII

                                                  The HTTP method we should use to call status_callback. Can be: GET or POST and defaults to POST.

                                                  voice_application_sid
                                                  Optional
                                                  post sid<AP> Not PII

                                                  The SID of the application we should use to handle phone calls to the phone number. If a voice_application_sid is present, we ignore all of the voice urls and use only those set on the application. Setting a voice_application_sid will automatically delete your trunk_sid and vice versa.

                                                  voice_caller_id_lookup
                                                  Optional
                                                  post boolean Not PII

                                                  Whether to lookup the caller's name from the CNAM database and post it to your app. Can be: true or false and defaults to false.

                                                  voice_fallback_method
                                                  Optional
                                                  post http_method Not PII

                                                  The HTTP method that we should use to call voice_fallback_url. Can be: GET or POST and defaults to POST.

                                                  voice_fallback_url
                                                  Optional
                                                  post url Not PII

                                                  The URL that we should call when an error occurs retrieving or executing the TwiML requested by url.

                                                  voice_method
                                                  Optional
                                                  post http_method Not PII

                                                  The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.

                                                  voice_url
                                                  Optional
                                                  post url Not PII

                                                  The URL that we should call to answer a call to the phone number. The voice_url will not be called if a voice_application_sid or a trunk_sid is set.

                                                  emergency_status
                                                  Optional
                                                  post enum:emergency_status Not PII

                                                  The configuration status parameter that determines whether the phone number is enabled for emergency calling.

                                                  emergency_address_sid
                                                  Optional
                                                  post sid<AD> Not PII

                                                  The SID of the emergency address configuration to use for emergency calling from this phone number.

                                                  trunk_sid
                                                  Optional
                                                  post sid<TK> Not PII

                                                  The SID of the Trunk we should use to handle phone calls to the phone number. If a trunk_sid is present, we ignore all of the voice urls and voice applications and use only those set on the Trunk. Setting a trunk_sid will automatically delete your voice_application_sid and vice versa.

                                                  voice_receive_mode
                                                  Optional
                                                  post enum:voice_receive_mode Not PII

                                                  The configuration parameter for the phone number to receive incoming voice calls or faxes. Can be: fax or voice and defaults to voice.

                                                  identity_sid
                                                  Optional
                                                  post sid<RI> Not PII

                                                  The SID of the Identity resource that we should associate with the phone number. Some regions require an identity to meet local regulations.

                                                  address_sid
                                                  Optional
                                                  post sid<AD> Not PII

                                                  The SID of the Address resource we should associate with the phone number. Some regions require addresses to meet local regulations.

                                                  bundle_sid
                                                  Optional
                                                  post sid<BU> Not PII

                                                  The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

                                                  Example 1
                                                        
                                                        
                                                        
                                                        Example 2
                                                              
                                                              
                                                              
                                                              Twilio will send a HTTP request to this URL when a call is received by your phone number

                                                              Update IncomingPhoneNumber to use a new Voice URL

                                                              Twilio will send a HTTP request to this URL when a call is received by your phone number
                                                              Example 3
                                                                    
                                                                    
                                                                    
                                                                    Twilio will send a HTTP request to this URL when an SMS is sent to your phone number

                                                                    Update IncomingPhoneNumber to use a new SMS URL

                                                                    Twilio will send a HTTP request to this URL when an SMS is sent to your phone number

                                                                    Delete an IncomingPhoneNumber resource

                                                                    delete
                                                                    https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json

                                                                    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.

                                                                    Parameters
                                                                    Parameters in REST API format
                                                                    account_sid
                                                                    Path
                                                                    delete sid<AC> Not PII

                                                                    The SID of the Account that created the IncomingPhoneNumber resources to delete.

                                                                    sid
                                                                    Path
                                                                    delete sid<PN> Not PII

                                                                    The Twilio-provided string that uniquely identifies the IncomingPhoneNumber resource to delete.

                                                                    Example 1
                                                                          
                                                                          
                                                                          
                                                                          Rate this page:

                                                                          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 by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

                                                                                
                                                                                
                                                                                

                                                                                Thank you for your feedback!

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

                                                                                Sending your feedback...
                                                                                🎉 Thank you for your feedback!
                                                                                Something went wrong. Please try again.

                                                                                Thanks for your feedback!

                                                                                Refer us and get $10 in 3 simple steps!

                                                                                Step 1

                                                                                Get link

                                                                                Get a free personal referral link here

                                                                                Step 2

                                                                                Give $10

                                                                                Your user signs up and upgrade using link

                                                                                Step 3

                                                                                Get $10

                                                                                1,250 free SMSes
                                                                                OR 1,000 free voice mins
                                                                                OR 12,000 chats
                                                                                OR more