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

Purchase an incoming phone number

Creates a new incoming phone number for an account. Provide optional voice and SMS routing settings, callback URLs, and a friendly name to configure the purchased number when it is created.

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

1 parameter · 24 body fields
AccountSidstringrequired
The account SID that will create the incoming phone number. Must be a 34-character SID matching the `AC` account SID format.

Optional configuration for the incoming phone number to purchase.

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 new 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 of the `sms_*_url` urls and use those set on 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 only 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.
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.
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.
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.
PhoneNumberstringoptional
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.
AreaCodestringoptional
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).

1 status code
201Returns the created incoming phone number resource, including its assigned SID, phone number, capabilities, origin, timestamps, and routing configuration.
account_sidstringoptional
The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created this IncomingPhoneNumber 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 this IncomingPhoneNumber 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
typestringoptional
The phone number type.

Error handling

AccountSid must be a 34-character account SID beginning with AC. HTTP method fields must be GET or POST, application SIDs must be 34-character AP SIDs, and URL fields must contain valid URIs.