PinpointSMSVoiceV2 / Client / list_available_phone_numbers

list_available_phone_numbers

PinpointSMSVoiceV2.Client.list_available_phone_numbers(**kwargs)

Retrieves a list of phone numbers that are available to request, based on the country, capabilities, and number type that you specify. You can optionally provide a number preference to return only numbers that match a specific digit pattern.

If no numbers match your search, this operation returns an empty list rather than an error. This operation currently supports only TEN_DLC number types in the US.

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) –

    An optional selection preference used to return only phone numbers that match a specific digit pattern, such as numbers that start with, end with, or contain a particular sequence. You can specify at most one preference. Number preferences apply only to TEN_DLC numbers in the US.

    • (dict) –

      A single number preference that specifies how to match available phone numbers. Each preference pairs a match type with one or more filter values.

      • 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