Sign in

v1

latestOpenAPI 3.0.0Apache 2.0 License2026-07-14109583546.7 KB

Releases an existing origination phone number in your account. Once released, a phone number is no longer available for sending messages.

If the origination phone number has deletion protection enabled or is associated with a pool, an error is returned.

post/#X-Amz-Target=PinpointSMSVoiceV2.ReleasePhoneNumber

Headers

X-Amz-Target'PinpointSMSVoiceV2.ReleasePhoneNumber' required

Request body

PhoneNumberIdstring required
<p>The PhoneNumberId or PhoneNumberArn of the phone number to release. You can use <a>DescribePhoneNumbers</a> to get the values for PhoneNumberId and PhoneNumberArn.</p> <important> <p>If you are using a shared End User Messaging SMS resource then you must use the full Amazon Resource Name(ARN).</p> </important>

Response

Success

PhoneNumberArnstring

The PhoneNumberArn of the phone number that was released.

PhoneNumberIdstring

The PhoneNumberId of the phone number that was released.

PhoneNumberstring

The phone number that was released.

Status'PENDING' | 'ACTIVE' | 'ASSOCIATING' | 'DISASSOCIATING' | 'DELETED'

The current status of the request.

IsoCountryCodestring

The two-character code, in ISO 3166-1 alpha-2 format, for the country or region.

MessageType'TRANSACTIONAL' | 'PROMOTIONAL'

The message type that was associated with the phone number.

NumberCapabilitiesNumberCapability[]

Specifies if the number could be used for text messages, voice, or both.

NumberType'SHORT_CODE' | 'LONG_CODE' | 'TOLL_FREE' | 'TEN_DLC' | 'SIMULATOR'

The type of number that was released.

MonthlyLeasingPricestring

The monthly price of the phone number, in US dollars.

TwoWayEnabledboolean

By default this is set to false. When set to true you can receive incoming text messages from your end recipients.

TwoWayChannelArnstring

The Amazon Resource Name (ARN) of the TwoWayChannel.

TwoWayChannelRolestring

An optional IAM Role Arn for a service to assume, to be able to post inbound SMS messages.

SelfManagedOptOutsEnabledboolean

By default this is set to false. When set to false and an end recipient sends a message that begins with HELP or STOP to one of your dedicated numbers, End User Messaging SMS automatically replies with a customizable message and adds the end recipient to the OptOutList. When set to true you're responsible for responding to HELP and STOP requests. You're also responsible for tracking and honoring opt-out requests.

OptOutListNamestring

The name of the OptOutList that was associated with the phone number.

RegistrationIdstring

The unique identifier for the registration.

CreatedTimestampstring date-time

The time when the phone number was created, in <a href="https://www.epochconverter.com/">UNIX epoch time</a> format.