An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio or ported 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.
/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}
| Property | Description |
|---|---|
| Sid | A 34 character string that uniquely identifies this resource. |
| DateCreated | The date that this resource was created, given as GMT RFC 2822 format. |
| DateUpdated | The date that this resource was last updated, given as GMT RFC 2822 format. |
| FriendlyName | 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. |
| AccountSid | The unique id of the Account responsible for this phone number. |
| PhoneNumber | The incoming phone number. e.g., +16175551212 (E.164 format) |
| ApiVersion | Calls to this phone number will start a new TwiML session with this API version. |
| VoiceCallerIdLookup | Look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Either true or false. |
| VoiceUrl | The URL Twilio will request when this phone number receives a call. |
| VoiceMethod | The HTTP method Twilio will use when requesting the above Url. Either GET or POST. |
| VoiceFallbackUrl | The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by Url. |
| VoiceFallbackMethod | The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST. |
| StatusCallback | The URL that Twilio will request to pass status parameters (such as call ended) to your application. |
| StatusCallbackMethod | The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST. |
| VoiceApplicationSid | 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. |
| SmsUrl | The URL Twilio will request when receiving an incoming SMS message to this number. |
| SmsMethod | The HTTP method Twilio will use when making requests to the SmsUrl. Either GET or POST. |
| SmsFallbackUrl | The URL that Twilio will request if an error occurs retrieving or executing the TwiML from SmsUrl. |
| SmsFallbackMethod | The HTTP method Twilio will use when requesting the above URL. Either GET or POST. |
| SmsApplicationSid | 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. |
| Uri | The URI for this resource, relative to https://api.twilio.com. |
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.
You may specify one or more of the following parameters to update this phone number's respective properties:
| Parameter | Description |
|---|---|
| FriendlyName | A human readable description of the new incoming phone number resource, with maximum length 64 characters. |
| ApiVersion | Calls to this phone number will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01. |
| VoiceUrl | The URL that Twilio should request when somebody dials the phone number. |
| VoiceMethod | The HTTP method that should be used to request the VoiceUrl. Either GET or POST. |
| VoiceFallbackUrl | A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by VoiceUrl. |
| VoiceFallbackMethod | The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST. |
| StatusCallback | The URL that Twilio will request to pass status parameters (such as call ended) to your application. |
| StatusCallbackMethod | The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST. |
| VoiceCallerIdLookup | Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. |
| VoiceApplicationSid | 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. |
| SmsUrl | The URL that Twilio should request when somebody sends an SMS to the new phone number. |
| SmsMethod | The HTTP method that should be used to request the SmsUrl. Either GET or POST. |
| SmsFallbackUrl | A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl. |
| SmsFallbackMethod | The HTTP method that should be used to request the SmsFallbackUrl. Either GET or POST. |
| SmsApplicationSid | 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. |
| AccountSid | The unique 34 character id of the account to which you wish to transfer this phone number. See Exchanging Numbers Between Subaccounts. |
Set the VoiceUrl and SmsUrl on a phone number to 'http://myapp.com/awesome'
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.
/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.
The following query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:
| Parameter | Description |
|---|---|
| PhoneNumber | Only show the incoming phone number resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit. |
| FriendlyName | Only show the incoming phone number resources with friendly names that exactly match this name. |
Return the set of phone numbers that match exactly (415) 867-5309.
Return the set of all phone numbers containing the digits 867.
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.
To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.
Your request must include exactly one of the following parameters:
| Parameter | Description |
|---|---|
| PhoneNumber | 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. |
| AreaCode | 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) |
If you include both parameters, we will use the AreaCode parameter and ignore
the PhoneNumber provided.
Your request may include the following parameters:
| Parameter | Description |
|---|---|
| FriendlyName | A human readable description of the new incoming phone number. Maximum 64 characters. Defaults to a formatted version of the number. |
| VoiceUrl | The URL that Twilio should request when somebody dials the new phone number. |
| VoiceMethod | The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST. |
| VoiceFallbackUrl | A URL that Twilio will request if an error occurs requesting or executing the TwiML at Url. |
| VoiceFallbackMethod | The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST. Defaults to POST. |
| StatusCallback | The URL that Twilio will request to pass status parameters (such as call ended) to your application. |
| StatusCallbackMethod | The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST. Defaults to POST. |
| VoiceCallerIdLookup | 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. |
| VoiceApplicationSid | 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. |
| SmsUrl | The URL that Twilio should request when somebody sends an SMS to the phone number. |
| SmsMethod | The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST. |
| SmsFallbackUrl | A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl. |
| SmsFallbackMethod | The HTTP method that should be used to request the SmsFallbackUrl. Must be either GET or POST. Defaults to POST. |
| SmsApplicationSid | 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. |
| ApiVersion | The Twilio REST API version to use for incoming calls made to this number. If omitted, uses 2010-04-01. |
If successful, Twilio responds with a representation of the new phone number that was assigned to your account.
Not Supported.
Not Supported.
POSTing to this resource allows you to request a new local phone number be added to your account. This subresource represents only Local phone numbers, i.e. not toll-free numbers.
/2010-04-01/Accounts/{YourAccountSid}/IncomingPhoneNumbers/Local
Returns a list of local <IncomingPhoneNumber> elements, each representing
a local (not toll-free) phone number given to your account, under an
<IncomingPhoneNumbers> list element that includes paging information.
Works exactly the same as the IncomingPhoneNumber resource, but filters out
toll-free numbers.
Adds a new phone number to 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 can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.
To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.
Your request must include PhoneNumber. We do not support AreaCode for this subresource:
| Parameter | Description |
|---|---|
| PhoneNumber | 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 this to have your POST succeed. |
The optional parameters for this request are exactly the same as
POSTing directly to the IncomingPhoneNumbers/ resource.
If successful, Twilio responds with a representation of the new phone number that was assigned to your account.
Not Supported.
Not Supported.
This subresource represents only toll-free phone numbers. POSTing to this resource allows you to request a new toll-free phone number be added to your account.
/2010-04-01/Accounts/{YourAccountSid}/IncomingPhoneNumbers/TollFree
Returns a list of local <IncomingPhoneNumber> elements, each representing a
toll-free phone number given to your account, under an <IncomingPhoneNumbers>
list element that includes paging information. Works exactly the same
as the IncomingPhoneNumber resource, but filters out all numbers that aren't
toll-free.
Adds a new phone number to 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 can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.
To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.
Your request must include PhoneNumber. We do not support AreaCode for this subresource:
| Parameter | Description |
|---|---|
| PhoneNumber | 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 this to have your POST succeed. |
The optional parameters for this request are exactly the same as
POSTing directly to the IncomingPhoneNumbers/ resource.
If successful, Twilio will respond with a representation of the new phone number that was assigned to your account.
Not Supported.
Not Supported.