Amazon Connect : ListPhoneNumbersV2Command API

4 min readJul 17, 2023

In this blog lets look at list phone numbers claimed to Amazon Connect instance or traffic distribution group.

ListPhoneNumbersV2Command is a class in the Amazon Connect SDK that allows you to list phone numbers claimed to your Amazon Connect instance or traffic distribution group. It provides the following functionalities:

Lists phone numbers claimed to your Amazon Connect instance or traffic distribution group.
Supports listing phone numbers in both AWS Regions associated with the traffic distribution group.
Requires the Amazon Resource Name (ARN) of the Amazon Connect instance or traffic distribution group as input.
Returns a list of phone numbers claimed to the specified instance or group.

To use the ListPhoneNumbersV2Command, you need to provide the following parameters:

input: An instance of the ListPhoneNumbersV2CommandInput class that contains the necessary input parameters.
Returns an instance of the ListPhoneNumbersV2CommandOutput class.

Parameters :

TargetARN ( string) — The Amazon Resource Name (ARN) for Amazon Connect instances or traffic distribution groups that phone numbers are claimed to. If TargetArn input is not provided, this API lists numbers claimed to all the Amazon Connect instances belonging to your account in the same Amazon Web Services Region as the request.

MaxResults (number) — The maximum number of results to return per page.

NextToken ( string ) — The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

PhoneNumberCountryCodes (list) — ISO country code.

PhoneNumberPrefix ( string ) — The prefix of the phone number. If provided, it must contain + as part of the country code.

PhoneNumberTypes (string ) — The type of phone number.

InstanceId (string) — We can also pass amazon connect’s instanceid in input.

Request Syntax :

{
    TargetArn:'string',
    MaxResults:123,
    NextToken:'string',
    PhoneNumberCountryCodes:['AF'|'AL'|'DZ'],// more countrycode available at documentation. 
    PhoneNumberTypes:['TOLL_FREE'|'DID'],
    PhoneNumberPrefix='string'
}

Response Syntax :

{
    'NextToken': 'string',
    'ListPhoneNumbersSummaryList': [
        {
            'PhoneNumberId': 'string',
            'PhoneNumberArn': 'string',
            'PhoneNumber': 'string',
            'PhoneNumberCountryCode': 'AF'|'AL'|'DZ'
            'PhoneNumberType': 'TOLL_FREE'|'DID',
            'TargetArn': 'string'
        },
    ]
}

Here’s an example of how you can use the ListPhoneNumbersV2Command in JavaScript:

import { ConnectClient, ListPhoneNumbersV2Command } from "@aws-sdk/client-connect";
    export const handler = async (event) => {
        // Create an instance of the ConnectClient
        const client = new ConnectClient({ region: "us-east-1" });
        // Create an instance of the ListPhoneNumbersV2CommandInput class
        const input = {
            InstanceId: "YourInstanceId"
        };
    
        const command = new ListPhoneNumbersV2Command(input);
        const response = await client.send(command);
        console.log("ListPhoneNumbersSummaryList -", response['ListPhoneNumbersSummaryList']);
        // Repeat API request until you get null as NextToken in Response. You can store phoneNumberSummaryList in Database. 
        return response;
    
 };

Response :

{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+123456789",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "US",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "TOLL_FREE",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    {
      "PhoneNumber": "+1234567898",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123453389:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "CA",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "DID",
      "TargetArn": "arn:aws:connect:us-east-1:123453389:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

Get TOLL_FREE numbers by CountryCode:
In input parameter you can pass PhoneNumberCountryCodes and PhoneNumberTypes as Toll_free.

      const input = {
          MaxResults: 100,
          PhoneNumberCountryCodes:['US'],
          PhoneNumberTypes:["TOLL_FREE"]
       };

Response :

{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+123456789",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "US",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "TOLL_FREE",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

Get DID numbers by CountryCode:
In input parameter you can pass PhoneNumberCountryCodes and PhoneNumberTypes as DID.

  const input = {
          MaxResults: 100,
          PhoneNumberCountryCodes:['GB'],
          PhoneNumberTypes:["DID"]
    };

Response :

{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+123456789",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "GB",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "DID",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

Get Phone numbers by TargetARN :

Along with NextToken and MaxResults pass TargetARN in input parameters.

const input = {
      MaxResults: 5,
      NextToken: "",
      TargetArn: "arn:aws:connect:us-east-1:123456789:instance/yourinstance-id"
   };

Response :

{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+123456789",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "US",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "TOLL_FREE",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

Get Phone numbers by PhoneNumberPrefix :

Along with NextToken and MaxResults pass PhoneNumberPrefix in input parameters. For example, pass “+1” to get phone number with prefix +1.

const input = {
    MaxResults: 10,
    NextToken: "",
    PhoneNumberPrefix:"+1"
  };

Response: 
{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+123456789",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "US",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "TOLL_FREE",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

Get Phone numbers by PhoneNumber :

Along with NextToken and MaxResults pass PhoneNumber in input parameter to get particular phone number. PhoneNumber should be number type.

const input = {
      MaxResults: 3,
      NextToken: "",
      PhoneNumber: +19994723995,
   };

Response :

{
"ListPhoneNumbersSummaryList": [
   {
      "PhoneNumber": "+19994723995",
      "PhoneNumberArn": "arn:aws:connect:us-east-1:123456789:phone-number/123sjfgsjdhfg34343ksfk9",
      "PhoneNumberCountryCode": "US",
      "PhoneNumberId": "123123somephonenumberid23",
      "PhoneNumberType": "TOLL_FREE",
      "TargetArn": "arn:aws:connect:us-east-1:123456789:instance/yourinstanceid"
    },
    . 
    .
  ],
  "NextToken": "AgV4B9e/nL9Fu2X6Bi="
}

After listing phone numbers in Amazon Connect we can use ClaimPhoneNumberCommand to claim an available phone number to your Amazon Connect instance or traffic distribution group.

Reference :
I took reference from AWS JavaScriptSDK V3 for this blog. https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/connect/command/ListPhoneNumbersV2Command

That’s it. Thanks for reading this. Please leave your comments. See you in another blog.

Amazon Connect : ListPhoneNumbersV2Command API

Written by Solomon Mark