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 |
1.3 Create end-user object with the type: starter_customer_profile_information
Please note that you cannot reuse contact information per each Starter Brand you create.
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: |
1.4 Create supporting document: customer_profile_address
Create an address for the Customer Profile.
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 |
Once you have a valid address SID from the previous step (beginning with AD
), you can create a customer document. This customer document will later be assigned to the empty Starter customer profile that you created.
1.5 Assign end-user, supporting document, and primary customer profile to the empty starter customer profile that you created
You will now attach the SIDs from all the steps above to the Starter Customer Profile:
- End-User Object SID (step 1.3): Begins with
IT
. - Starter Customer Profile SID (step 1.2): Begins with
BU
. - Supporting Document SID (step 1.4): Begins with
RD
.
1.5.1 Attach the end-user (from Step 1.3) to the Starter Customer Profile
1.5.2 Attach the supporting document (from Step 1.4) to the Starter Customer Profile
1.5.3 Attach the primary_customer_profile to the Starter Customer Profile
As an ISV registering one of your customers, you will need to attach the primary_customer_profile
that you created for your own company to the bundle of information represented by this Starter Customer Profile.
Both the Primary Customer Profile and the Starter Customer Profile SIDs start with BU
. Be sure to note the example SIDs below and in the code sample for this step for a reference on where to pass each SID. Remember, these are just examples and you will pass your own unique SIDs for this step.
- Starter Customer Profile SID:
BU48886180931dcaa8cbdc2033cf880b7a
. Passed in the URL path. - Primary Customer Profile SID:
BU07d54228ef3eee5c6bffca3d2bd567fb
. Passed as theObjectSid
.
1.6 Evaluate the Starter Customer Profile
What does this do? This step will evaluate the Starter Customer Profile against the Starter Customer Profile Policy RN806dd6cd175f314e1f96a9727ee271f4
.
The response’s status
parameter has two valid string values:
compliant
noncompliant
1.7 Submit the Starter Customer Profile for review
The response’s status
parameter has multiple valid string values:
draft
pending-review
in-review
twilio-rejected
twilio-approved
2. Create an A2P Starter Profile and attach required information
Once you have finished creating a Starter Customer Profile you are ready to create an A2P Starter Profile. Let's do that!
What does this do? This step creates an A2P Starter Profile — a bundle of information — that will be sent to The Campaign Registry.
Which API does it use? The Trusthub API.
2.1 Fetch an A2P Starter Profile Policy
Fetch the policy for A2P Messaging using a Trust Hub policy with the identifier RN670d5d2e282a6130ae063b234b6019c8
.
Request:
curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN --location \
--request GET https://trusthub.twilio.com/v1/Policies/RN670d5d2e282a6130ae063b234b6019c8
Response:
{
"url": "https://trusthub.twilio.com/v1/Policies/RN670d5d2e282a6130ae063b234b6019c8",
"requirements": {
"end_user": [],
"supporting_trust_products": [],
"supporting_document": [
[]
],
"supporting_customer_profiles": [
{
"type": "primary_customer_profile_type_business",
"name": "Primary Customer Profile Bundle Proof",
"requirement_name": "primary_customer_profile"
},
{
"type": "secondary_customer_profile_type_business",
"name": "Secondary Customer Profile Bundle Proof",
"requirement_name": "secondary_customer_profile"
},
{
"type": "starter_customer_profile_type_business",
"name": "Starter Customer Profile Proof",
"requirement_name": "starter_customer_profile"
}
]
},
"friendly_name": "Starter A2P Messaging: Local - Business",
"sid": "RN670d5d2e282a6130ae063b234b6019c8"
}
2.2 Create an empty A2P Starter Trust Bundle
In the response of this step, an A2P Starter Trust bundle SID will be returned (starting with BU
). Jot this SID down as you will need it in the next step.
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 A2P Messaging TrustHub policy identifier. The hard-coded value is |
2.3 Assign the Starter Customer Profile bundle to the A2P Starter trust bundle
In this step you will use the A2P Starter trust bundle SID from Step 2.2 and the Starter Customer Profile SID from Step 1.2.
Both the A2P Starter trust bundle and the Starter Customer Profile SIDs start with BU
. Be sure to note the example SIDs below and in the code sample for this step for a reference on where to pass each SID. Remember, these are just examples and you will pass your own unique SIDs for this step.
- A2P Starter Trust Bundle SID:
BU70cb4e72a8486190e181b25c1180c348
. Passed in the URL path. - Starter Customer Profile SID:
BU48886180931dcaa8cbdc2033cf880b7a
. Passed as theobjectSid
.
2.4 Evaluate the A2P Starter Profile Bundle
Evaluate the A2P Starter Profile Bundle using the Policy SID RN670d5d2e282a6130ae063b234b6019c8
.
The response’s status
parameter has two valid string values:
compliant
noncompliant
By running an evaluation, you check that all the necessary A2P Bundle information has been added. If there are no errors, you will get a status of compliant
. If there are errors, the evaluation will fail and error codes will be surfaced to you.
2.5 Submit the A2P Starter Profile bundle for review
Submit the A2P Starter Profile bundle for review using the Policy SID RN670d5d2e282a6130ae063b234b6019c8
.
At this point, you can proceed immediately to the next step, "Create an A2P Brand". It is normal for your A2P Starter Profile to remain in the Pending state until your Brand is approved.
3. Create an A2P Brand
What does this do? This step submits the combined package of your customers' A2P Messaging profile and Customer Profile with the STARTER
BrandType
to The Campaign Registry.
Which API does it use? The Messaging API.
You can make a GET request using curl to check the status of your brand registration. To do so, you will pass your brand SID (starting with BN
).
Request:
curl -X GET 'https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Response:
{
"status":"APPROVED",
"brand_score":42,
"date_updated":"2021-09-15T18:51:40Z",
"customer_profile_bundle_sid":"BUXXXXXXXXXXXXX",
"russell_3000":null,
"account_sid":"ACXXXXXXXXXXXXX",
"brand_type":"STARTER",
"a2p_profile_bundle_sid":"BUXXXXXXXXXXXXX",
"identity_status":"SELF_DECLARED",
"url":"https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNXXXXXXXXXXXXX",
"sid":"BNXXXXXXXXXXXXX",
"tax_exempt_status":null,
"date_created":"2021-09-15T18:51:39Z",
"failure_reason":null,
"skip_automatic_sec_vet":false,
"mock":false,
"tcr_id":"BXXXXXX"
}
Parameter | Valid Values |
status |
|
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. |
4. Create a Messaging Service
What does this do? This step sets up a Messaging Service and adds up to five US A2P 10 DLC numbers to it.
Which API does it use? The Messaging API.
Handling Inbound Messages
To configure your Messaging Service to ensure you receive inbound messages, you will need to configure a webhook url using the inbound_request_url
parameter. You’ll also want to configure a fallback webhook url in case the primary handler fails, using the fallback_url
parameter.
If you would like your inbound messages webhook URL to be set at the phone number level and not at the Messaging Service level, make sure to set use_inbound_webhook_on_number
to true
when creating your Messaging Service.
5. Create an A2P SMS Campaign use case
The Campaign Registry (TCR) recently announced several changes to the A2P campaign creation process, which will go live on November 17, 2022. They now require the collection of additional data and have added new length requirements for certain data fields. For more details, please see this support article. For a full overview of the API changes, see our API Documentation for Campaign Registration Changes.
We've made it! We're now finally ready to create an A2P SMS Campaign Use Case.
What does this do? This step creates a Starter Campaign use case for sending A2P messages.
Which API does it use? The Messaging API.
5.1 Create an A2P Messaging Campaign Use Case
Create the Messaging campaign using use case STARTER
.
Selecting a Starter use case will automatically register a mixed type use case to allow for maximum flexibility. This behavior is different from registering a Standard Brand, where you must choose specific use cases.
Please Note: You may only create 1 Campaign per customer. If you need to create multiple Campaigns, you will need to register your customer with Standard Customer Profile and create a Standard A2P Brand using the ISV Standard API Guide.
If your A2P Brand registration has failed or is not yet approved, you will recieve an error when making this api call. Please ensure that your brand registration status is APPROVED
before continuing with this step.
What’s next?
Congratulations! 🎉 You now have a registered A2P campaign! If you already had an existing Messaging Service with phone numbers you are ready to start sending messages. If you created new Messaging Services, you will need to add phone numbers to that Messaging Service:
- Learn how to add phone numbers to a Messaging Service with the PhoneNumber Resource.
- Check out the Twilio Messaging Services API documentation to learn more about the
Service
resource.
Get help with A2P 10DLC
Need help building or registering your A2P 10DLC application? Learn more about Twilio Professional Services for A2P 10DLC.
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.