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 three capabilities: basic phone number claiming, descriptive metadata, and prefix-based filtering.

Phone numbers must be claimed to an existing Amazon Connect instance. The examples are intentionally small. Combine them with your own Connect instance configuration and call routing flows.

Claim a phone number for a Connect instance

Contact centers start by claiming phone numbers from AWS’s inventory and associating them with a Connect instance.

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 available phone number inventory for a number matching your countryCode and type, then claims it to the Connect instance specified by targetArn. The type property determines whether you get a direct inward dialing (DID) number or a toll-free number. The tags property adds metadata for organization and cost tracking.

Add a description to identify the number’s purpose

Teams managing multiple phone numbers add descriptions to track which numbers serve which business functions.

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",
    description: "example description",
});

import pulumi
import pulumi_aws as aws

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

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"),
			Description: pulumi.String("example description"),
		})
		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",
        Description = "example description",
    });

});

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")
            .description("example description")
            .build());

    }
}

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

The description property stores human-readable text explaining the number’s purpose. This metadata appears in the AWS Console and helps operators understand which numbers route to which departments or services.

Filter available numbers by prefix pattern

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

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 filters available phone numbers by pattern. AWS searches its inventory for numbers starting with your specified prefix, which must include the + and country code (e.g., +18005 for US toll-free numbers starting with 1-800-5). This helps you claim vanity numbers or numbers in specific area codes.

Beyond these examples

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

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

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

Phone number status monitoring (statuses output)
Regional placement (region property)
Import of existing phone numbers

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 phone number types are available?

You can provision two types: TOLL_FREE for toll-free numbers or DID (Direct Inward Dialing) for standard phone numbers.

What is the targetArn used for?

The targetArn specifies which Amazon Connect instance the phone number will be claimed to. This is required and links the number to your Connect instance.

Do I need to specify a region?

The region property is required but defaults to the region configured in your provider, so you typically don’t need to specify it explicitly.

Phone Number Selection

How do I filter available phone numbers by prefix?

Use the prefix property to filter numbers, for example "+18005" to find US numbers starting with 1-800-5. The prefix must include the + as part of the country code.

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

The prefix argument is only used during initial provisioning to filter available numbers. Including it during import will cause errors since the number is already claimed.

Immutability & Lifecycle

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

The countryCode, type, description, and prefix properties are all immutable. Changing any of these requires destroying and recreating the phone number resource.

What do the different phone number statuses mean?

CLAIMED indicates the number is successfully provisioned and ready to use, IN_PROGRESS means provisioning is underway, and FAILED indicates provisioning encountered an error.

Using a different cloud?

Explore integration guides for other cloud providers:

Azure Guides GCP Guides