Configure AWS Connect Phone Numbers

The aws:connect/phoneNumber:PhoneNumber resource, part of the Pulumi AWS provider, claims phone numbers from AWS’s available inventory and associates them with Amazon Connect instances. This guide focuses on two capabilities: basic number claiming and prefix-based inventory filtering.

Phone numbers belong to Amazon Connect instances and must reference an existing instance ARN. The examples are intentionally small. Combine them with your own Connect instance configuration and contact flow routing.

Claim a phone number for a Connect instance

Contact centers need phone numbers to handle inbound and outbound calls. AWS maintains an inventory of available numbers that you claim by specifying country and type.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.connect.PhoneNumber("example", {
    targetArn: exampleAwsConnectInstance.arn,
    countryCode: "US",
    type: "DID",
    tags: {
        hello: "world",
    },
});

import pulumi
import pulumi_aws as aws

example = aws.connect.PhoneNumber("example",
    target_arn=example_aws_connect_instance["arn"],
    country_code="US",
    type="DID",
    tags={
        "hello": "world",
    })

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/connect"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := connect.NewPhoneNumber(ctx, "example", &connect.PhoneNumberArgs{
			TargetArn:   pulumi.Any(exampleAwsConnectInstance.Arn),
			CountryCode: pulumi.String("US"),
			Type:        pulumi.String("DID"),
			Tags: pulumi.StringMap{
				"hello": pulumi.String("world"),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.Connect.PhoneNumber("example", new()
    {
        TargetArn = exampleAwsConnectInstance.Arn,
        CountryCode = "US",
        Type = "DID",
        Tags = 
        {
            { "hello", "world" },
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.connect.PhoneNumber;
import com.pulumi.aws.connect.PhoneNumberArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new PhoneNumber("example", PhoneNumberArgs.builder()
            .targetArn(exampleAwsConnectInstance.arn())
            .countryCode("US")
            .type("DID")
            .tags(Map.of("hello", "world"))
            .build());

    }
}

resources:
  example:
    type: aws:connect:PhoneNumber
    properties:
      targetArn: ${exampleAwsConnectInstance.arn}
      countryCode: US
      type: DID
      tags:
        hello: world

When you create the resource, AWS searches its inventory for an available number matching your criteria and claims it to your Connect instance. The targetArn property specifies which instance receives the number. The countryCode and type properties filter the inventory; type can be “DID” (direct inward dialing) or “TOLL_FREE”. The tags property adds metadata for organization and cost tracking.

Filter available numbers by prefix pattern

Organizations with specific number requirements can filter AWS’s inventory to find matching patterns.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.connect.PhoneNumber("example", {
    targetArn: exampleAwsConnectInstance.arn,
    countryCode: "US",
    type: "DID",
    prefix: "+18005",
});

import pulumi
import pulumi_aws as aws

example = aws.connect.PhoneNumber("example",
    target_arn=example_aws_connect_instance["arn"],
    country_code="US",
    type="DID",
    prefix="+18005")

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/connect"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := connect.NewPhoneNumber(ctx, "example", &connect.PhoneNumberArgs{
			TargetArn:   pulumi.Any(exampleAwsConnectInstance.Arn),
			CountryCode: pulumi.String("US"),
			Type:        pulumi.String("DID"),
			Prefix:      pulumi.String("+18005"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.Connect.PhoneNumber("example", new()
    {
        TargetArn = exampleAwsConnectInstance.Arn,
        CountryCode = "US",
        Type = "DID",
        Prefix = "+18005",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.connect.PhoneNumber;
import com.pulumi.aws.connect.PhoneNumberArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new PhoneNumber("example", PhoneNumberArgs.builder()
            .targetArn(exampleAwsConnectInstance.arn())
            .countryCode("US")
            .type("DID")
            .prefix("+18005")
            .build());

    }
}

resources:
  example:
    type: aws:connect:PhoneNumber
    properties:
      targetArn: ${exampleAwsConnectInstance.arn}
      countryCode: US
      type: DID
      prefix: '+18005'

The prefix property narrows the search to numbers starting with a specific pattern, useful for vanity numbers or local area codes. The prefix must include the country code with a leading plus sign (e.g., “+18005” for US toll-free numbers starting with 1-800-5). AWS claims the first available number matching all criteria.

Beyond these examples

These snippets focus on specific phone number features: number claiming and inventory filtering, and tagging and metadata. They’re intentionally minimal rather than full contact center deployments.

The examples reference pre-existing infrastructure such as Amazon Connect instances (targetArn). They focus on claiming numbers rather than provisioning the Connect instance itself.

To keep things focused, common phone number patterns are omitted, including:

Number status monitoring (statuses output)
Cross-region number management
Number release and reclaiming

These omissions are intentional: the goal is to illustrate how phone number claiming is wired, not provide drop-in contact center modules. See the Connect PhoneNumber resource reference for all available configuration options.

Let's configure AWS Connect Phone Numbers

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Configuration & Setup

What are the required properties to create a phone number?

You must specify targetArn (the Connect instance ARN), countryCode (ISO country code), type (either TOLL_FREE or DID), and region.

What's the difference between TOLL_FREE and DID phone numbers?

These are the two valid phone number types. TOLL_FREE numbers are free for callers to dial, while DID (Direct Inward Dialing) numbers are standard phone numbers that route to your Connect instance.

Phone Number Selection & Filtering

How do I request a phone number with a specific prefix?

Use the prefix property to filter available numbers. The prefix must include + as part of the country code (e.g., "+18005" to get numbers starting with 1-800-5).

What format will my phone number be in?

Phone numbers are formatted as [+] [country code] [subscriber number including area code].

What do the phone number statuses mean?

The statuses field shows claiming progress: CLAIMED means successfully claimed, IN_PROGRESS means claiming is underway, and FAILED means the claim attempt failed.

Immutability & Updates

What properties can't I change after creating a phone number?

The following properties are immutable: countryCode, type, description, and prefix. Changing any of these requires replacing the resource.

Import & State Management

Why can't I specify prefix when importing an existing phone number?

The prefix property is only used during creation to filter available numbers. When importing an existing phone number, omit this argument since the number is already claimed.

Using a different cloud?

Explore integration guides for other cloud providers:

Azure Guides GCP Guides