US Basic Branded Calling

(new)

Public Beta

US Basic Branded Calling is currently available as a Public Beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by a Twilio SLA.

Display your business name on the called party's mobile phone when they receive your call. This helps your customers identify your calls and increases the likelihood that they will answer.

Note: Branded Calling works on mobile phones. For landlines, use Caller ID Name (CNAM) instead.

Coverage

US Basic Branded Calling supports the following networks:

Country	Network
United States	T-Mobile, Verizon

Eligibility

US Basic Branded Calling is available for both direct customers of Twilio and Independent Software Vendors (ISVs). If you need assistance with the Branded Calling registration process, contact your Twilio account manager.

To use Branded Calling, you must meet the following requirements:

You have legal authority to use the Branded Calling display name.
You can't use Branded Calling for illegal purposes, such as to deceive or mislead customers. If you get a high number of SIP 608 or 603 responses in your outbound calls, you might not be able to use Branded Calling. Learn more about recommendations and best practices for maintaining a positive caller reputation.

Prerequisites

Before you begin, you must complete the following tasks:

Purchase one or more Twilio phone numbers.
Create a Primary or Secondary Business Profile and have it approved.
Create a Voice Integrity instance and have it approved. Voice Integrity lets you register your phone numbers with analytic vendors to reduce spam labeling. Learn more about how to onboard Voice Integrity.
Register your phone numbers with the Business Profile and with Voice Integrity. You'll need your Voice Integrity SID.
Prepare a short description of your Branded Calling use case.

Register your brand

In the Twilio Console, on the Branded Calling Trust Product page, click Register branded calling and follow the instructions.

Branded Calling bundle guidelines

When you register your brand, keep the following in mind:

A Branded Calling bundle is associated with one display name and one or more phone numbers.
A phone number can be associated with only one Branded Calling bundle.
You must create a new Branded Calling bundle for each display name you want to register.

Display name restrictions

Maximum 15 characters for Verizon and 32 characters for T-Mobile
Must be related to your business name
Must not contain Personally Identifiable Information (PII)
Must not contain web links
Letters and numbers only

For more information, see the Branded Calling FAQ.

Review process

When you register your brand, Twilio reviews your submission to make sure it meets all requirements. The review process can take up to seven days.

Billing

All applicable Branded Calling fees will be charged to the account where the Branded Calling bundle is created.

Manage your Branded Calling bundle

You can use the Trust Products API to manage your Branded Calling bundle.

Assign phone numbers to your Branded Calling bundle

In the Twilio Console, on the Branded Calling Trust Product page, click Branded Calling.
Select a Branded Calling bundle you want to update.
Click the Assigned phone numbers tab.
Click Add phone numbers, select the phone numbers you want to add, and click Save.

Twilio reviews the new assigned phone numbers before adding them to the Branded Calling bundle. This can take 24 to 48 hours.

Unassign phone numbers from your Branded Calling bundle

(information)

Info

It can take 24 to 48 hours for the carrier to fully remove the branded display name from their system.

In the Twilio Console, on the Branded Calling Trust Product page, click Branded Calling.
Select a Branded Calling bundle you want to update.
Click the Assigned phone numbers tab.
Select the phone numbers you want to remove, and click Unassign.

The phone numbers will no longer be associated with the Branded Calling bundle and won't display the branded display name.

API requests

You can do the following tasks using the Trust Products API:

Assign phone numbers to your Branded Calling bundle

Make a POST /v1/TrustProducts/YOUR_BRANDED_CALLING_SID/ChannelEndpointAssignments request to assign phone numbers to your Branded Calling bundle.

Your Branded Calling SID begins with BU. You can find the Branded Calling SID on the Branded Calling Trust Product page in the Trust Hub.
Your Phone Number SID begins with PN. Make sure that you've registered the phone number with your Voice Integrity instance.
The response includes an Sid that starts with RA. This is the Assignment SID that you'll use to unassign the phone number later.

Learn how to check your Branded Calling SIDs, Phone Number SIDs, and Business Profile SIDs.

(warning)

Warning

The ChannelEndpointType or channel_endpoint_type value must be phone-number. Don't change this value.

Assign phone numbers to your Branded Calling bundle

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createTrustProductChannelEndpointAssignment() {
11  const trustProductsChannelEndpointAssignment = await client.trusthub.v1
12    .trustProducts("YOUR_BRANDED_CALLING_SID")
13    .trustProductsChannelEndpointAssignment.create({
14      channelEndpointSid: "YOUR_PHONE_NUMBER_SID",
15      channelEndpointType: "phone-number",
16    });
17
18  console.log(trustProductsChannelEndpointAssignment.sid);
19}
20
21createTrustProductChannelEndpointAssignment();

Response

1{
2  "sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "trust_product_sid": "YOUR_BRANDED_CALLING_SID",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "channel_endpoint_sid": "YOUR_PHONE_NUMBER_SID",
6  "channel_endpoint_type": "phone-number",
7  "date_created": "2019-07-31T02:34:41Z",
8  "url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
9}

Retrieve Assignment SIDs

Make a GET /v1/TrustProducts/YOUR_BRANDED_CALLING_SID/ChannelEndpointAssignments request to retrieve a list of Assignment SIDs (Sid) for your Branded Calling bundle.

Retrieve a list of Assignment SIDs

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listTrustProductChannelEndpointAssignment() {
11  const trustProductsChannelEndpointAssignments = await client.trusthub.v1
12    .trustProducts("YOUR_BRANDED_CALLING_SID")
13    .trustProductsChannelEndpointAssignment.list({ limit: 20 });
14
15  trustProductsChannelEndpointAssignments.forEach((t) => console.log(t.sid));
16}
17
18listTrustProductChannelEndpointAssignment();

Response

1{
2  "results": [
3    {
4      "sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "channel_endpoint_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8      "channel_endpoint_type": "phone-number",
9      "date_created": "2019-07-31T02:34:41Z",
10      "url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
11    }
12  ],
13  "meta": {
14    "page": 0,
15    "page_size": 50,
16    "first_page_url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments?ChannelEndpointSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
17    "previous_page_url": null,
18    "url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments?ChannelEndpointSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
19    "next_page_url": null,
20    "key": "results"
21  }
22}

Unassign a phone number from your Branded Calling bundle

Make a DELETE /v1/TrustProducts/YOUR_BRANDED_CALLING_SID/ChannelEndpointAssignments/YOUR_ASSIGNMENT_SID request to unassign a phone number from your Branded Calling bundle.

When you unassign a phone number, it's no longer associated with the Branded Calling bundle and doesn't display the display name when making calls.

Unassign a phone number from your Branded Calling bundle

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteTrustProductChannelEndpointAssignment() {
11  await client.trusthub.v1
12    .trustProducts("YOUR_BRANDED_CALLING_SID")
13    .trustProductsChannelEndpointAssignment("YOUR_ASSIGNMENT_SID")
14    .remove();
15}
16
17deleteTrustProductChannelEndpointAssignment();

Additional API requests

Check your Branded Calling SIDs, Phone Number SIDs, and Business Profile SIDs.

Retrieve Branded Calling SIDs

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listTrustProduct() {
11  const trustProducts = await client.trusthub.v1.trustProducts.list({
12    limit: 20,
13  });
14
15  trustProducts.forEach((t) => console.log(t.sid));
16}
17
18listTrustProduct();

Response

1{
2  "results": [
3    {
4      "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "policy_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "friendly_name": "friendly_name",
8      "status": "twilio-approved",
9      "email": "email",
10      "status_callback": "http://www.example.com",
11      "valid_until": "2020-07-31T01:00:00Z",
12      "date_created": "2019-07-30T22:29:24Z",
13      "date_updated": "2019-07-31T01:09:00Z",
14      "url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "links": {
16        "trust_products_entity_assignments": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",
17        "trust_products_evaluations": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
18        "trust_products_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"
19      },
20      "errors": null
21    }
22  ],
23  "meta": {
24    "page": 0,
25    "page_size": 50,
26    "first_page_url": "https://trusthub.twilio.com/v1/TrustProducts?Status=draft&FriendlyName=friendly_name&PolicySid=RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
27    "previous_page_url": null,
28    "url": "https://trusthub.twilio.com/v1/TrustProducts?Status=draft&FriendlyName=friendly_name&PolicySid=RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
29    "next_page_url": null,
30    "key": "results"
31  }
32}

Retrieve Phone Number SIDs from a parent account

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listIncomingPhoneNumber() {
11  const incomingPhoneNumbers = await client.incomingPhoneNumbers.list({
12    limit: 20,
13  });
14
15  incomingPhoneNumbers.forEach((i) => console.log(i.accountSid));
16}
17
18listIncomingPhoneNumber();

Response

1{
2  "end": 0,
3  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0",
4  "incoming_phone_numbers": [
5    {
6      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "address_requirements": "none",
8      "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "api_version": "2010-04-01",
10      "beta": null,
11      "capabilities": {
12        "voice": true,
13        "sms": false,
14        "mms": true,
15        "fax": false
16      },
17      "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",
18      "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",
19      "emergency_status": "Active",
20      "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21      "emergency_address_status": "registered",
22      "friendly_name": "(808) 925-5327",
23      "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "origin": "origin",
25      "phone_number": "+18089255327",
26      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27      "sms_application_sid": "",
28      "sms_fallback_method": "POST",
29      "sms_fallback_url": "",
30      "sms_method": "POST",
31      "sms_url": "",
32      "status_callback": "",
33      "status_callback_method": "POST",
34      "trunk_sid": null,
35      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
36      "voice_application_sid": "",
37      "voice_caller_id_lookup": false,
38      "voice_fallback_method": "POST",
39      "voice_fallback_url": null,
40      "voice_method": "POST",
41      "voice_url": null,
42      "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
43      "voice_receive_mode": "voice",
44      "status": "in-use",
45      "subresource_uris": {
46        "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"
47      }
48    }
49  ],
50  "next_page_uri": null,
51  "page": 0,
52  "page_size": 50,
53  "previous_page_uri": null,
54  "start": 0,
55  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0"
56}

Retrieve Business Profile SIDs

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listCustomerProfile() {
11  const customerProfiles = await client.trusthub.v1.customerProfiles.list({
12    limit: 20,
13  });
14
15  customerProfiles.forEach((c) => console.log(c.sid));
16}
17
18listCustomerProfile();

Response

1{
2  "results": [
3    {
4      "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "policy_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "friendly_name": "friendly_name",
8      "status": "twilio-approved",
9      "email": "email",
10      "status_callback": "http://www.example.com",
11      "valid_until": "2020-07-31T01:00:00Z",
12      "date_created": "2019-07-30T22:29:24Z",
13      "date_updated": "2019-07-31T01:09:00Z",
14      "url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "links": {
16        "customer_profiles_entity_assignments": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",
17        "customer_profiles_evaluations": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",
18        "customer_profiles_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"
19      },
20      "errors": [
21        {
22          "code": 18601
23        }
24      ]
25    }
26  ],
27  "meta": {
28    "page": 0,
29    "page_size": 50,
30    "first_page_url": "https://trusthub.twilio.com/v1/CustomerProfiles?Status=draft&FriendlyName=friendly_name&PolicySid=RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
31    "previous_page_url": null,
32    "url": "https://trusthub.twilio.com/v1/CustomerProfiles?Status=draft&FriendlyName=friendly_name&PolicySid=RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
33    "next_page_url": null,
34    "key": "results"
35  }
36}

Retrieve phone number assignments for a Business profile

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listCustomerProfileChannelEndpointAssignment() {
11  const customerProfilesChannelEndpointAssignments = await client.trusthub.v1
12    .customerProfiles("YOUR_BUSINESS_PROFILE_SID")
13    .customerProfilesChannelEndpointAssignment.list({ limit: 20 });
14
15  customerProfilesChannelEndpointAssignments.forEach((c) => console.log(c.sid));
16}
17
18listCustomerProfileChannelEndpointAssignment();

Response

1{
2  "results": [
3    {
4      "sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "channel_endpoint_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8      "channel_endpoint_type": "phone-number",
9      "date_created": "2019-07-31T02:34:41Z",
10      "url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
11    }
12  ],
13  "meta": {
14    "page": 0,
15    "page_size": 50,
16    "first_page_url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments?ChannelEndpointSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
17    "previous_page_url": null,
18    "url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments?ChannelEndpointSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",
19    "next_page_url": null,
20    "key": "results"
21  }
22}

Next steps

Learn about using US Enhanced Branded Calling to display your logo and call reason in addition to your branded display name.
Learn more about Customer Profiles and other Trust Products in the Trust Hub documentation.
Learn more about the Customer Profiles API and Trust Products API.