Sample - Twilio API
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json

Purchase a toll-free incoming phone number

Creates a toll-free incoming phone number in the specified Account. Supply PhoneNumber in E.164 format and optionally configure the API version, friendly name, messaging callbacks, voice callbacks, and application SIDs. The response contains the created phone number and its assigned resource metadata.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 23 body fields
AccountSidstringrequired
The 34-character SID of the Account that will create the resource, matching the `AC` prefix.

Form data for purchasing and configuring a toll-free incoming phone number. PhoneNumber identifies the number to purchase.

PhoneNumberstringrequired
The phone number to purchase specified in [E.164](https://www.twilio.com/docs/glossary/what-e164) format. E.164 phone numbers consist of a + followed by the country code and subscriber number without punctuation characters. For example, +14155551234.
ApiVersionstringoptional
The API version to use for incoming calls made to the new phone number. The default is `2010-04-01`.
FriendlyNamestringoptional
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 phone number.
SmsApplicationSidstringoptional
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 `sms_*_url` values and use those of the application.
SmsFallbackMethodstringoptional
The HTTP method that we should use to call `sms_fallback_url`. Can be: `GET` or `POST` and defaults to `POST`.
Allowed:GETPOST
SmsFallbackUrlstringoptional
The URL that we should call when an error occurs while requesting or executing the TwiML defined by `sms_url`.
SmsMethodstringoptional
The HTTP method that we should use to call `sms_url`. Can be: `GET` or `POST` and defaults to `POST`.
Allowed:GETPOST
SmsUrlstringoptional
The URL we should call when the new phone number receives an incoming SMS message.
StatusCallbackstringoptional
The URL we should call using the `status_callback_method` to send status information to your application.
StatusCallbackMethodstringoptional
The HTTP method we should use to call `status_callback`. Can be: `GET` or `POST` and defaults to `POST`.
Allowed:GETPOST
VoiceApplicationSidstringoptional
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 those set on the application. Setting a `voice_application_sid` will automatically delete your `trunk_sid` and vice versa.
VoiceCallerIdLookupbooleanoptional
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`.
VoiceFallbackMethodstringoptional
The HTTP method that we should use to call `voice_fallback_url`. Can be: `GET` or `POST` and defaults to `POST`.
Allowed:GETPOST
VoiceFallbackUrlstringoptional
The URL that we should call when an error occurs retrieving or executing the TwiML requested by `url`.
VoiceMethodstringoptional
The HTTP method that we should use to call `voice_url`. Can be: `GET` or `POST` and defaults to `POST`.
Allowed:GETPOST
VoiceUrlstringoptional
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.
IdentitySidstringoptional
The SID of the Identity resource that we should associate with the new phone number. Some regions require an Identity to meet local regulations.
AddressSidstringoptional
The SID of the Address resource we should associate with the new phone number. Some regions require addresses to meet local regulations.
EmergencyStatusstringoptional
The parameter displays if emergency calling is enabled for this number. Active numbers may place emergency calls by dialing valid emergency numbers for the country.
Allowed:ActiveInactive
EmergencyAddressSidstringoptional
The SID of the emergency address configuration to use for emergency calling from the new phone number.
TrunkSidstringoptional
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.
VoiceReceiveModestringoptional
Allowed:voicefax
BundleSidstringoptional
The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

1 status code
201Returns the created incoming phone number with its Account and Address SIDs, address requirements, API version, capabilities, timestamps, friendly name, phone number, origin, resource SID, and SMS configuration.
account_sidstringoptional
The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the resource.
address_sidstringoptional
The SID of the Address resource associated with the phone number.
address_requirementsstringoptional
Whether the phone number requires an [Address](https://www.twilio.com/docs/usage/api/address) registered with Twilio. Can be: `none`, `any`, `local`, or `foreign`.
Allowed:noneanylocalforeign
api_versionstringoptional
The API version used to start a new TwiML session.
betabooleanoptional
Whether the phone number is new to the Twilio platform. Can be: `true` or `false`.
capabilitiesobjectoptional
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_createdstringoptional
The date and time in GMT that the resource was created specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updatedstringoptional
The date and time in GMT that the resource was last updated specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
friendly_namestringoptional
The string that you assigned to describe the resource.
identity_sidstringoptional
The SID of the Identity resource that we associate with the phone number. Some regions require an Identity to meet local regulations.
phone_numberstringoptional
The phone number in [E.164](https://www.twilio.com/docs/glossary/what-e164) format, which consists of a + followed by the country code and subscriber number.
originstringoptional
The phone number's origin. `twilio` identifies Twilio-owned phone numbers and `hosted` identifies hosted phone numbers.
sidstringoptional
The unique string that that we created to identify the resource.
sms_application_sidstringoptional
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_methodstringoptional
The HTTP method we use to call `sms_fallback_url`. Can be: `GET` or `POST`.
Allowed:GETPOST
sms_fallback_urlstringoptional
The URL that we call when an error occurs while retrieving or executing the TwiML from `sms_url`.
sms_methodstringoptional
The HTTP method we use to call `sms_url`. Can be: `GET` or `POST`.
Allowed:GETPOST
sms_urlstringoptional
The URL we call when the phone number receives an incoming SMS message.
status_callbackstringoptional
The URL we call using the `status_callback_method` to send status information to your application.
status_callback_methodstringoptional
The HTTP method we use to call `status_callback`. Can be: `GET` or `POST`.
Allowed:GETPOST
trunk_sidstringoptional
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.
uristringoptional
The URI of the resource, relative to `https://api.twilio.com`.
voice_receive_modestringoptional
Allowed:voicefax
voice_application_sidstringoptional
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_lookupbooleanoptional
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_methodstringoptional
The HTTP method we use to call `voice_fallback_url`. Can be: `GET` or `POST`.
Allowed:GETPOST
voice_fallback_urlstringoptional
The URL that we call when an error occurs retrieving or executing the TwiML requested by `url`.
voice_methodstringoptional
The HTTP method we use to call `voice_url`. Can be: `GET` or `POST`.
Allowed:GETPOST
voice_urlstringoptional
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_statusstringoptional
The parameter displays if emergency calling is enabled for this number. Active numbers may place emergency calls by dialing valid emergency numbers for the country.
Allowed:ActiveInactive
emergency_address_sidstringoptional
The SID of the emergency address configuration that we use for emergency calling from this phone number.
emergency_address_statusstringoptional
The status of address registration with emergency services. A registered emergency address will be used during handling of emergency calls from this number.
Allowed:registeredunregisteredpending-registrationregistration-failurepending-unregistrationunregistration-failure
bundle_sidstringoptional
The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.
statusstringoptional

Error handling

PhoneNumber is required and must use E.164 phone-number format. AccountSid, SmsApplicationSid, and VoiceApplicationSid must be 34-character SIDs with AC or AP prefixes respectively, while callback URL fields must use URI format and HTTP method fields must be GET or POST.