ISV US A2P 10DLC Starter Registration: API Walkthrough

Updates are coming to Twilio’s Starter Brand registration based on changes from The Campaign Registry (TCR) and mobile carriers. We will provide updates on how this change may impact US A2P 10DLC registration as soon as they are available. Brands with EINs will no longer be able to use Twilio's Starter Brand registration going forward.

In the meantime, if you are registering on behalf of an organization with an EIN/Tax ID, please complete a Standard registration.

Please rate limit all API requests for Brand and Campaign registration to 1 request per second.

This guide is a step-by-step walk through the various API calls you will make to register your customer as a Starter Brand. This involves three different APIs to cover the main actions:

Trust Hub registration.
Brand registration.
Campaign use case creation.

For more information on the Starter Brand tier, which is available to ISVs registering their customers for A2P 10DLC, please see our Starter Brand Overview. In fact, we recommend taking the short time to read the overview before following the steps below.

Additionally, be sure you're using the latest version of the Twilio Helper Libraries to perform the API calls in this walkthrough.

Prerequisite: create a TrustHub Profile for your company

What does this do? It creates a TrustHub Primary Customer Profile for your ISV business.

Which API does it use? None — this task can only be completed in the Trust Hub UI in the Twilio Console.

Before proceeding with the Starter Brand onboarding process for your customers, you must have a Primary Customer Profile in an APPROVED state. You can do this in the Trust Hub UI.

To maximize Trust Scores, please enter the exact legal name, address, and other details as registered for your legal entity. US-based organizations can enter their EIN into this publicly searchable database to get the registered information.

Tip Save the Primary Customer Profile SID from your Profile Details (parent account) so it can be used in a later step. It will begin with BU.

Registration steps overview

To register your customer as a Starter Brand, you will need to complete these steps and the relevant substeps:

Create a Starter Customer Profile and attach the required information to that profile.
Create an A2P Starter Profile and attach the required information to that profile.
Create an A2P Brand.
Create a Messaging Service.
Create an A2P SMS Campaign use case.

What you will create:

Starter Customer Profile: During the Starter Brand registration process, you will supply information about your customer including their name, email, phone number, and physical address. Twilio will then create a Starter Customer Profile populated with the customer information you provide.
A2P Brand (Starter): The object that gets registered with The Campaign Registry (TCR). The Starter Brand contains all of the supplied information from the Starter Customer Profile and the A2P Starter Bundle.
Messaging Service: A bundling of multiple Twilio senders (phone numbers) with a common set of features and configuration. For more information on Messaging Services, please see our Messaging Services guide.
A2P SMS Campaign use case: An A2P 10DLC use case for your brand that will show the intent of the messages you send with your Messaging Service.

1. Create Starter Customer Profile(s) and attach required information

Please note: You should collect unique contact information for each Starter Customer Profile you create. Contact information cannot be duplicated across Starter Customer Profiles.

In your requests throughout this walkthrough, you should be using the Twilio Account SID (and corresponding Auth Token) where you plan to use the Brand you are registering for. For example, if you use subaccounts to separate your customers' usage, use the Twilio Account SID corresponding to the subaccount for the customer you are registering.

Before you begin, please be sure to use the latest version of the Twilio helper libraries. You can find our SDKs here.

Policy SIDs are static, so please use the exact SID shown below in your requests.

What does this do? This step creates Starter Customer Profiles for each of your customers using a Trust Hub policy with the identifier RN806dd6cd175f314e1f96a9727ee271f4. Trust Hub supports many types of compliance collections, but this specific policy is for Starter profiles.

Which API does it use? The Trusthub API.

1.1 Fetch the Starter Customer Profile Policy

Request:

curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN --location \
  --request GET https://trusthub.twilio.com/v1/Policies/RN806dd6cd175f314e1f96a9727ee271f4

Response:

{
  "url": "https://trusthub.twilio.com/v1/Policies/RN806dd6cd175f314e1f96a9727ee271f4",
  "requirements": {
    "end_user": [
      {
        "url": "/EndUserTypes/starter_customer_profile_information",
        "fields": [
          "first_name",
          "last_name",
          "email",
          "phone_number"
        ],
        "type": "starter_customer_profile_information",
        "name": "Information",
        "requirement_name": "starter_customer_profile_information"
      }
    ],
    "supporting_trust_products": [],
    "supporting_document": [
      [
        {
          "description": "Customer Profile Address",
          "type": "document",
          "name": "Customer Profile Address",
          "accepted_documents": [
            {
              "url": "/SupportingDocumentTypes/customer_profile_address",
              "fields": [
                "address_sids"
              ],
              "type": "customer_profile_address",
              "name": "Legal Company Address"
            }
          ],
          "requirement_name": "customer_profile_address"
        }
      ]
    ],
    "supporting_customer_profiles": [
      {
        "type": "primary_customer_profile_type_business",
        "name": "Primary Customer Profile Bundle",
        "requirement_name": "primary_customer_profile"
      }
    ]
  },
  "friendly_name": "Starter Customer Profile of type Business",
  "sid": "RN806dd6cd175f314e1f96a9727ee271f4"
}

1.2 Create an empty Starter Customer Profile Bundle

You should complete this step by supplying your customer’s FriendlyName and Email.

Parameter	Valid Values
`friendly_name`	A string value representing your customer's business name.
`email`	A string value representing your customer's email address.
`policy_sid`	The static TrustHub policy identifier for Starter profiles. The hard-coded value is `RN806dd6cd175f314e1f96a9727ee271f4`.

Parameter	Valid Values
`attributes`	An object containing your customer's first name, last name, email address, and phone number.
`friendly_name`	A string value representing the end-user object you create in this step.
`type`	The end user object type: `starter_customer_profile_information`.

Parameter *( = Required)**	Valid Values
Customer Name	String value representing your customer's name.
Street Address 1 *	Example: 1234 Your Street Name
Street Address 2	Example: Apt B (if applicable)
City*	Example: San Francisco
Region*	Can be a State or Province. For example, California (US State) and British Columbia (Canadian Province).
Postal Code*	Example: 94016
IsoCountry	Please see this list of valid IsoCountry codes.

Parameter	Valid Values
`status`	"PENDING" "APPROVED" "FAILED"
`tcr_id`	Only assigned after a successful "APPROVED" brand registration. The value will be null otherwise.
`brand_score`	Only assigned after a successful "APPROVED" brand registration. The value will be null otherwise.
`failure_reason`	Only present for an unsuccessful "FAILED" brand registration. It is not present otherwise.

Create an empty Starter Customer Profile Bundle

Create end-user object with the type: starter_customer_profile_information

Create supporting document: customer_profile_address

Create a customer document

Attach the end-user to Starter Customer Profile

Attach the supporting document to Starter Customer Profile

Attach the primary_customer_profile to Starter Customer Profile

Evaluate the Starter Customer Profile

Submit the Starter Customer Profile for review

Create an empty A2P Starter Trust Bundle

Assign the Starter Customer Profile bundle to the A2P Starter trust bundle

Evaluate the A2P Starter Profile Bundle

Submit the A2P Starter Profile bundle for review

Create an A2P Brand

Create a Messaging Service

Create an A2P Messaging Campaign use case

Get help with A2P 10DLC

Need some help?

Thank you for your feedback!

Thanks for your feedback!