PinpointSMSVoiceV2 / Client / list_available_phone_numbers

list_available_phone_numbers

PinpointSMSVoiceV2.Client.list_available_phone_numbers(**kwargs)

Search available phone numbers from aggregator inventory, optionally filtered by pattern. If NumberPreference is omitted, returns unfiltered available numbers. Returns empty list (not an exception) when no numbers match. ResourceNotFoundException is thrown only for invalid RegistrationId (campaign not found).

See also: AWS API Documentation

Request Syntax

response = client.list_available_phone_numbers(
    IsoCountryCode='string',
    NumberCapabilities=[
        'SMS'|'VOICE'|'MMS'|'RCS',
    ],
    NumberType='TEN_DLC',
    RegistrationId='string',
    NumberPreference=[
        {
            'PreferenceType': [
                'StartsWith'|'EndsWith'|'Contains'|'ExactMatch',
            ],
            'Filter': [
                'string',
            ]
        },
    ],
    NextToken='string',
    MaxResults=123
)

Parameters:

• IsoCountryCode (string) –

  [REQUIRED]

  The two-character code, in ISO 3166-1 alpha-2 format, for the country or region in which to search for available phone numbers. This operation currently supports only US.

• NumberCapabilities (list) –

  [REQUIRED]

  The capabilities to filter by, such as SMS. Only phone numbers that support all of the specified capabilities are returned.

  • (string) –

• NumberType (string) –

  [REQUIRED]

  The type of phone number to search for.

• RegistrationId (string) –

  The registration associated with the request. A registration is required for regulated number types. You can specify either:

  • The unique identifier of the registration.

  • The Amazon Resource Name (ARN) of the registration.

• NumberPreference (list) –

  Optional. If omitted, returns unfiltered available numbers. Max 1 element for List API.

  • (dict) –

    A single number preference — specifies a pattern type and filter value.

    • PreferenceType (list) – [REQUIRED]

      The type of match to apply to the filter values.

      • StartsWith: Returns numbers that begin with the filter value.

      • EndsWith: Returns numbers that end with the filter value.

      • Contains: Returns numbers that contain the filter value.

      • ExactMatch: Returns the number that exactly matches the filter value.

      • (string) –

        The type of pattern matching to apply.

    • Filter (list) – [REQUIRED]

      The digit pattern values to match against available phone numbers, using the specified preference type.

      • (string) –

        A filter value — either a pattern (e.g., “+1510”) or full E.164 number.

• NextToken (string) – The token returned from a previous request to retrieve the next page of results.

• MaxResults (integer) – The maximum number of results to return per page. If you don’t specify a value, the default is 10.

Return type:

dict

Returns:

Response Syntax

{
    'AvailablePhoneNumbers': [
        'string',
    ],
    'NextToken': 'string'
}

Response Structure

• (dict) –

  • AvailablePhoneNumbers (list) –

    An array of phone numbers, in E.164 format, that are available to request based on the specified filters.

    • (string) –

  • NextToken (string) –

    The token to include in the next request to retrieve the next page of results. This value is null when there are no more results.

Exceptions

• PinpointSMSVoiceV2.Client.exceptions.ThrottlingException

• PinpointSMSVoiceV2.Client.exceptions.AccessDeniedException

• PinpointSMSVoiceV2.Client.exceptions.ResourceNotFoundException

• PinpointSMSVoiceV2.Client.exceptions.ValidationException

• PinpointSMSVoiceV2.Client.exceptions.ConflictException

• PinpointSMSVoiceV2.Client.exceptions.InternalServerException