Menu

Expand
Rate this page:

ISV US A2P 10DLC API Registration Overview

The APIs described in this guide are subject to change. Many of the option for the fields are not detailed here but will be in the release version of the API.

This guide provides an overview of getting started on Twilio with A2P 10DLC (Application-to-person, 10-Digit Long Code) messaging. It covers the steps you follow to create customer profiles for your company and your clients, as well as how to register those profiles for A2P 10DLC capabilities, and create the required messaging campaign use cases.

If you are unfamiliar with the Twilio Trust Hub, please take a moment to read the Trust Hub Overview before you continue with this guide.

This guide contains two main sections:

  1. A general overview of the A2P 10DLC registration process.
  2. A walkthrough of example customer requirements.

Before proceeding, ISVs should before aware of the following considerations. You can find additional information around the A2P 10DLC pilot phase in this support article.

  • Future releases of these APIs will likely be backwards incompatible. We anticipate making improvements and changes that will not work with this release.

Registration process overview

The general process for registering for US A2P 10DLC capabilities involves the following steps, which can be broken into two phases: Trust Hub onboarding and brand and campaign registration.

Trust Hub onboarding for your organization and customers

The first step is to create a Primary Customer Profile (PCP) inside the Trust Hub. The PCP represents your company as a whole:

a2p-primary-customer-profile.png

Creating a PCP is a requirement for all subsequent steps but need only be done once. New PCPs must be approved, and this may take up to 24 hours. However, during the A2P transition phase, you can proceed to the next steps before this approval has been granted.

Once you have a PCP, create one Secondary Customer Profile (SCP) for each of your individual customers:

a2p-secondary-customer-profile.png

Creating SCPs with the Trust Hub API involves two steps:

  1. Creating a Customer Profile Bundle.
  2. Attaching required information, including a business address and the contact details of an authorized business representative, to the Bundle.
  3. Submit the Bundle for review via the Trust Hub API.

Brand and campaign use case registration for your customers

After you complete the Trust Hub onboarding — the creation of a PCP and a number of SCPs — you must register Brands and campaign use cases for each of your customers.

For each customer, create a US A2P brand. You will need to get some key information from your customers, such as the type of organization they represent — public company, private company, or non-profit, for example — and, where appropriate, their stock symbol.

us-a2p-brand.png

Using the Trust Hub API, create an A2P Product Bundle for each customer comprising their SCP and US A2P brand. You can then utilize the Bundle with the BrandRegistrations API to allow Twilio to submit the overall package, the Brand, to The Campaign Registry (TCR), a body sponsored by the communications industry.

a2p-brand.png

The TCR reviews all of the submitted information and returns a TCR Trust Score. The approval time of this review is a few seconds. At this point, the brand — a combination of the Customer Profile and US A2P brand — has been enrolled in US A2P 10DLC functionality. You can now proceed to the next step: creating campaign use cases.

a2p-campaign-use-cases.png

The Campaigns API allows you to programmatically create campaign use cases that you will attach to Twilio Messaging Services to enable sending A2P messages to your customers’ end-users.

A customer requirements example

Let’s quickly run through an example of an ISV use case and what actions would be required to enable US A2P 10DLC messaging.

As shown in the diagram below, Owl Inc. is a new software company. Two retailers, Acme Corp and Buy n Large, use Owl’s platform to send SMS messages to their own customers.

a2p-example-isv-usecase.png

Owl requires two-factor authentication to login to their platform, and they use Twilio to deliver their one-time passcodes.

Owl has separated its two retail customers, Acme and Buy n Large, into subaccounts to separate billing:

  • Acme sends order status updates by SMS to its customers.
  • Buy n Large sends promotional content, such as coupon codes, by SMS. It also offers private shopping appointments with their sales team.

In order to comply with the new US A2P 10DLC changes, Owl needs to create the following:

ISV - Subaccounts.png

  1. Owl needs to register the Owl Inc. Brand. its Brand consists of a Customer Profile and a US A2P brand. Owl pays a registration fee via Twilio to TCR, and TCR returns Owl’s Trust Score.
  2. Owl now needs to create a campaign use case for the messages that it sends directly for 2FA to its own customers.
  3. Since each of Owl’s customers (Acme and Buy n Large) can control their own message content, Owl must register those Brands, using a Secondary Customer Profile and a separate US A2P brand for each retailer. To do so, it needs to gather information from the retailers, directly or by building a registration portal with Twilio’s APIs for its customers to self-register.
  4. Finally, Owl must register a campaign use case for each type of traffic that its customers will be sending:
    • For Acme’s order status updates, it will register a campaign use case with Type=Account Notifications.
    • For Buy n Large, which sends promotional content, such as coupon codes, it will need to register a campaign use case with Type=Marketing.
    • Additionally, Owl will need to register a campaign use case for Buy n Large’s sales appointments use case with Type=Conversational Messaging. This is because these messages typically have a large number of back-and-forth interactions as Buy n Large’s customers find a good time slot.

What’s next?

This guide provided a general overview of the API-based registration process for ISVs to access US A2P 10DLC capabilities. For more information, please see:

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif