--- title: "POST /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json" method: POST path: "/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json" tags: ["Api20100401IncomingPhoneNumberTollFree"] --- # POST /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json `POST /2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json` ## Request - Base URL: `https://api.twilio.com` - URL: `https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.json` - Auth: HTTP basic ## Path parameters - `AccountSid` string, required ## Request body `application/x-www-form-urlencoded` - object - `PhoneNumber` string, phone-number, required: 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. - `ApiVersion` string: The API version to use for incoming calls made to the new phone number. The default is `2010-04-01`. - `FriendlyName` string: 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. - `SmsApplicationSid` string: 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. - `SmsFallbackMethod` 'GET' | 'POST', http-method: The HTTP method that we should use to call `sms_fallback_url`. Can be: `GET` or `POST` and defaults to `POST`. - `SmsFallbackUrl` string, uri: The URL that we should call when an error occurs while requesting or executing the TwiML defined by `sms_url`. - `SmsMethod` 'GET' | 'POST', http-method: The HTTP method that we should use to call `sms_url`. Can be: `GET` or `POST` and defaults to `POST`. - `SmsUrl` string, uri: The URL we should call when the new phone number receives an incoming SMS message. - `StatusCallback` string, uri: The URL we should call using the `status_callback_method` to send status information to your application. - `StatusCallbackMethod` 'GET' | 'POST', http-method: The HTTP method we should use to call `status_callback`. Can be: `GET` or `POST` and defaults to `POST`. - `VoiceApplicationSid` string: 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. - `VoiceCallerIdLookup` boolean: 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`. - `VoiceFallbackMethod` 'GET' | 'POST', http-method: The HTTP method that we should use to call `voice_fallback_url`. Can be: `GET` or `POST` and defaults to `POST`. - `VoiceFallbackUrl` string, uri: The URL that we should call when an error occurs retrieving or executing the TwiML requested by `url`. - `VoiceMethod` 'GET' | 'POST', http-method: The HTTP method that we should use to call `voice_url`. Can be: `GET` or `POST` and defaults to `POST`. - `VoiceUrl` string, uri: 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. - `IdentitySid` string: The SID of the Identity resource that we should associate with the new phone number. Some regions require an Identity to meet local regulations. - `AddressSid` string: The SID of the Address resource we should associate with the new phone number. Some regions require addresses to meet local regulations. - `EmergencyStatus` 'Active' | 'Inactive': 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. - `EmergencyAddressSid` string: The SID of the emergency address configuration to use for emergency calling from the new phone number. - `TrunkSid` string: 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. - `VoiceReceiveMode` 'voice' | 'fax' - `BundleSid` string: The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations. ## Response `201` Created - ApiV2010AccountIncomingPhoneNumberIncomingPhoneNumberTollFree - `account_sid` string, nullable: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the resource. - `address_sid` string, nullable: The SID of the Address resource associated with the phone number. - `address_requirements` 'none' | 'any' | 'local' | 'foreign': 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`. - `api_version` string, nullable: The API version used to start a new TwiML session. - `beta` boolean, nullable: Whether the phone number is new to the Twilio platform. Can be: `true` or `false`. - `capabilities` object, nullable: 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`. - `mms` boolean - `sms` boolean - `voice` boolean - `fax` boolean - `date_created` string, date-time-rfc-2822, nullable: The date and time in GMT that the resource was created specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format. - `date_updated` string, date-time-rfc-2822, nullable: 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_name` string, nullable: The string that you assigned to describe the resource. - `identity_sid` string, nullable: The SID of the Identity resource that we associate with the phone number. Some regions require an Identity to meet local regulations. - `phone_number` string, phone-number, nullable: 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. - `origin` string, nullable: The phone number's origin. `twilio` identifies Twilio-owned phone numbers and `hosted` identifies hosted phone numbers. - `sid` string, nullable: The unique string that that we created to identify the resource. - `sms_application_sid` string, nullable: 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` 'GET' | 'POST', http-method, nullable: The HTTP method we use to call `sms_fallback_url`. Can be: `GET` or `POST`. - `sms_fallback_url` string, uri, nullable: The URL that we call when an error occurs while retrieving or executing the TwiML from `sms_url`. - `sms_method` 'GET' | 'POST', http-method, nullable: The HTTP method we use to call `sms_url`. Can be: `GET` or `POST`. - `sms_url` string, uri, nullable: The URL we call when the phone number receives an incoming SMS message. - `status_callback` string, uri, nullable: The URL we call using the `status_callback_method` to send status information to your application. - `status_callback_method` 'GET' | 'POST', http-method, nullable: The HTTP method we use to call `status_callback`. Can be: `GET` or `POST`. - `trunk_sid` string, nullable: 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` string, nullable: The URI of the resource, relative to `https://api.twilio.com`. - `voice_receive_mode` 'voice' | 'fax' - `voice_application_sid` string, nullable: 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, nullable: 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` 'GET' | 'POST', http-method, nullable: The HTTP method we use to call `voice_fallback_url`. Can be: `GET` or `POST`. - `voice_fallback_url` string, uri, nullable: The URL that we call when an error occurs retrieving or executing the TwiML requested by `url`. - `voice_method` 'GET' | 'POST', http-method, nullable: The HTTP method we use to call `voice_url`. Can be: `GET` or `POST`. - `voice_url` string, uri, nullable: 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` 'Active' | 'Inactive': 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. - `emergency_address_sid` string, nullable: The SID of the emergency address configuration that we use for emergency calling from this phone number. - `emergency_address_status` 'registered' | 'unregistered' | 'pending-registration' | 'registration-failure' | 'pending-unregistration' | 'unregistration-failure': The status of address registration with emergency services. A registered emergency address will be used during handling of emergency calls from this number. - `bundle_sid` string, nullable: The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations. - `status` string, nullable ## Changes - **2025-01-09** (v2010) `806ef73f9b1e`: 2 info - api tag `Api20100401IncomingPhoneNumberTollFree` added - api tag `Api20100401TollFree` removed - **2024-04-18** (v2010) `cf63f47f41aa`: 20 breaking, 20 info - removed the enum value `DELETE` of the request property `SmsFallbackMethod` - removed the enum value `DELETE` of the request property `SmsMethod` - removed the enum value `DELETE` of the request property `StatusCallbackMethod` - removed the enum value `DELETE` of the request property `VoiceFallbackMethod` - …36 more [Operation history](https://skmtc.dev/twilio/apis/api-v2010/changes/2010-04-01/Accounts/:AccountSid/IncomingPhoneNumbers/TollFree.json/post.md) --- [API](https://skmtc.dev/twilio/apis/api-v2010.md) - [All operations](https://skmtc.dev/twilio/apis/api-v2010/llms.txt) - [OpenAPI document](https://skmtc.dev/twilio/apis/api-v2010/revisions/bfdf249a1298?raw)