--- title: "Create an Incoming Phone Number" method: POST path: "/Accounts/{AccountSid}/IncomingPhoneNumbers" tags: ["Incoming Phone Numbers"] --- # Create an Incoming Phone Number `POST /Accounts/{AccountSid}/IncomingPhoneNumbers` Create an Incoming Phone Number. #### Permissions The API token must include the following scopes: _Numbers_. ## Path parameters - `AccountSid` string, uuid, required ## Request body - CreateIncomingPhoneNumberRequest — Request body for creating an incoming phone number. - `AreaCode` string — The area code of your new number. - `PhoneNumber` string — The incoming number in E.164 format. - `AddressSid` string — The unique identifier for the address associated with this phone number. - `FriendlyName` string — A formatted version of the number. - `IdentitySid` string — The unique identifier for the identity associated with this phone number. - `SmsApplicationSid` string — The unique identifier for the application associated with SMS handling on this phone number. - `SmsFallbackMethod` 'GET' | 'POST' — Whether the request to `SmsFallbackUrl` is a `GET` or a `POST`. Default is `POST`. - `SmsFallbackUrl` string — The URL to request if errors occur when fetching SmsUrl. - `SmsMethod` 'GET' | 'POST' — Whether the request to SmsUrl is a `GET` or a `POST`. Default is `POST`. - `SmsUrl` string — The URL to request when an incoming SMS is received. - `StatusCallback` string — The URL to request to pass status updates to. - `StatusCallbackMethod` 'GET' | 'POST' — Whether the request to StatusCallback is a `GET` or a `POST`. Default is `POST`. - `TrunkSid` string — The unique identifier for the Trunk associated with this phone number. - `VoiceApplicationSid` string — The unique identifier for the application associated with call handling on this phone number. - `VoiceCallerIdLookup` boolean — Whether or not to look up a caller's name in the database. - `VoiceFallbackMethod` 'GET' | 'POST' — Whether the request to VoiceFallbackUrl is a `GET` or a `POST`. Default is `POST`. - `VoiceFallbackUrl` string — The URL to request if errors occur when fetching `Url`. - `VoiceMethod` 'GET' | 'POST' — Whether the request to Url is a `GET` or a `POST`. Default is `POST`. - `VoiceReceiveMode` 'voice' | 'fax' — Whether this number can receive calls or fax. Default is voice. - `VoiceUrl` string — The URL to request when an incoming call is received. ## Response `200` The request has succeeded. - IncomingPhoneNumberResponse — Response containing a single incoming phone number. - `account_sid` string, uuid — The unique identifier for the account that is associated with this phone number. - `address_requirements` 'none' | 'any' | 'local' | 'foreign' — Address requirements. - `address_sid` string — The unique identifier for the address associated with this phone number. - `api_version` string — The version of the SignalWire API. - `beta` boolean — New numbers on SignalWire are marked as beta. - `capabilities` IncomingPhoneNumberCapabilities — Phone number capabilities. - `Voice` boolean — Whether or not voice is enabled. - `SMS` boolean — Whether or not SMS is enabled. - `MMS` boolean — Whether or not MMS is enabled. - `Fax` boolean — Whether or not fax is enabled. - `date_created` string — The date, in RFC 2822 format, this phone number was created. - `date_updated` string — The date, in RFC 2822 format, this phone number was updated. - `emergency_address_sid` string — The unique identifier of the address associated with E911 for this phone number. - `emergency_status` 'active' | 'inactive' — Emergency status. - `friendly_name` string — A formatted version of the number. - `identity_sid` string — The unique identifier for the identity associated with this phone number. - `origin` 'signalwire' | 'hosted' — Phone number origin. - `phone_number` string — The incoming number in E.164 format. - `sid` string — The unique identifier for this phone number. - `sms_application_sid` string — The unique identifier for the application associated with SMS handling on this phone number. - `sms_fallback_method` string — Whether the request to `SmsFallbackUrl` is a `GET` or a `POST`. Default is `POST`. - `sms_fallback_url` string — The URL to request if errors occur when fetching SmsUrl. - `sms_method` string — Whether the request to SmsUrl is a `GET` or a `POST`. Default is `POST`. - `sms_url` string — The URL to request when an incoming SMS is received. - `status_callback` string — The URL to request to pass status updates to. - `status_callback_method` string — Whether the request to StatusCallback is a `GET` or a `POST`. Default is `POST`. - `trunk_sid` string — The unique identifier for the Trunk associated with this phone number. - `uri` string — The URI for this number. - `voice_application_sid` string — The unique identifier for the application associated with call handling on this phone number. - `voice_caller_id_lookup` boolean — Whether or not to look up a caller's name in the database. - `voice_fallback_method` string — Whether the request to VoiceFallbackUrl is a `GET` or a `POST`. Default is `POST`. - `voice_fallback_url` string — The URL to request if errors occur when fetching `Url`. - `voice_method` string — Whether the request to Url is a `GET` or a `POST`. Default is `POST`. - `voice_url` string — The URL to request when an incoming call is received. ## Other responses - `400` — 400 Bad Request response. - `401` — 401 Unauthorized response. ## Changes - **2026-01-15** `6b2611cfa74b` — 4 breaking - the request property `SmsApplicationSid` became not nullable - the request property `SmsFallbackUrl` became not nullable - the request property `SmsUrl` became not nullable - the request property `VoiceApplicationSid` became not nullable - **2026-01-15** `686ef84c2abc` — 5 breaking, 4 info - the response property `emergency_address_sid` became nullable for the status `200` - the response property `sms_application_sid` became nullable for the status `200` - the response property `sms_fallback_url` became nullable for the status `200` - the response property `sms_url` became nullable for the status `200` - …5 more - **2026-01-15** `3c88f14db21e` — 6 breaking, 4 warning, 25 info - request body became required - removed the media type `application/x-www-form-urlencoded` from the request body - the `address_requirements` response's property type changed from `string` to no type for status `200` - the `capabilities` response's property type changed from `object` to no type for status `200` - …31 more [Change history](https://skmtc.dev/signalwire/apis/compatibility-api/changes/Accounts/:AccountSid/IncomingPhoneNumbers/post.md) --- [API](https://skmtc.dev/signalwire/apis/compatibility-api.md) · [All operations](https://skmtc.dev/signalwire/apis/compatibility-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/signalwire/compatibility-api/revisions/dab5a930a50e/schema)