Troubleshooting and Resubmitting US A2P Brands
To register in the new US 10DLC ecosystem, companies must first create a record of their business called an A2P Brand. Information from this submission, including business name, tax identifier, and more is used to vet your business using various business verification sources.
Note: There are lighter versions of A2P Brands known as Starter Brands. Starter Brands require much less registration information and do not get the same level of vetting as a Standard Brand. This document only applies to Standard Brands. For more information on Starter Brands, please see the ISV Starter Brand overview.
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.
US A2P Brands can fail for a number of reasons. This guide will cover:
- Common errors and how to troubleshoot them
- How to resubmit your A2P Brands using the Console or API
Let's get started!
Common errors and troubleshooting
When you use the a2p/BrandRegistrations
endpoint to create a US A2P Brand, you'll get back many parameters relevant to your new brand, but some are specifically related to brand failures.
The brand_feedback
field is returned in the response when status
is FAILED
. This field contains a list of Feedback IDs, where each ID corresponds to a recommendation on how you can improve your brand score.
Below are a list of possible feedback IDs that can be returned and corresponding recommendations for fixing the required brand information:
Feedback ID | Recommendations |
TAX_ID |
Use your company's business registration number (which is EIN for U.S. customers or the equivalent for customers outside the U.S.). Use your company's legal name that you used in the tax filings. The information above needs to be an exact match to your company's tax fillings. If you need this information, we recommend using the EIN lookup service or contact your legal department. |
STOCK_SYMBOL |
Use your company's stock symbol. Use the stock exchange where your company stock is traded (i.e. NYSE, Nasdaq). |
GOVERNMENT_ENTITY |
If you are not a US based government entity, you should register as a private entity. Provide a dated letter on official letterhead from a US-based government entity stating that the organization is considered an instrument of a municipal, state, or federal government entity. |
NONPROFIT |
If you are not a US based government entity, you should register as a private entity. Provide an IRS nonprofit determination letter or Tax Form 990 from the latest tax year. |
For more information on how Brand approval works and best practices to get your brand approved, please see the A2P 10DLC Brand Approval Best Practices support article.
Resubmitting your Brands
Twilio supports resubmission of Brands in the unverified
state up to three times for free using either the Twilio Console or the Twilio A2P 10DLC API.
Using the Console
When a Brand registration fails within the Console, here’s what you can expect to see in your process to resubmit the Brand with correct information:
When submitted using the Twilio Console, Brands will show descriptive error messages. From here, you can click "Edit customer profile" to begin the process of editing and correcting your Brand information.
Using the API
Brands are the summation of many reusable Trust Hub components including Customer/Business Profiles and US A2P Profiles. Depending on what needs to be updated, you will need to update the underlying profile or end user in order to resubmit a Brand.
Let's look at an example. We have created a Brand with the following bits and pieces:
Item | Notes |
Secondary Business Profile | Holder for business information objects |
- EndUser (customer_profile_business_information ) |
Has things like the EIN, business name, and industry |
- EndUser (authorized_representative_1 ) |
Has our representative info |
- SupportingDocument (contains Address) | Has the business address |
A2P Messaging Profile | Holder for stock info object |
- EndUser (us_a2p_messaging_profile_information ) |
Has the stock info |
To create a Brand, you first create each one of the objects above as Twilio resources. Then, you roll them up into "Profiles". Together, a Business Profile plus a Messaging Profile equals one US A2P Brand.
When things go wrong with a Brand, editing the information means you must edit the underlying object. For example, if the address input was incorrect you'll need to go back and edit the Address object.
Testing out errors with Brand creation
Here, examine creating a Brand with an error as a demonstration. Instead of putting the correct EIN within the customer_profile_business_information
EndUser
, we just put "123456789". Let’s see what comes back in the Brand creation:
Request to create this US A2P Brand:
curl -X POST https://messaging.twilio.com/v1/a2p/BrandRegistrations \
--data-urlencode "CustomerProfileBundleSid=BUb4784f724e5b12f319296cf6fc521eeb" \
--data-urlencode "A2PProfileBundleSid=BUced9020cecf2910329dcab95938d7237" \
-u $DEC8_SID:$DEC8_TKN | json_pp
Reading the Brand's failure state:
The response won't immediately have anything useful since creating a Brand is an asynchronous process. Making GET requests to the Brand until we see a failure reason shows us the following response:
{
...
"brand_feedback" : [
"TAX_ID"
],
...
"status" : "FAILED",
...
}
Cutting out much of the response, the two key parameters we're looking for are brand_feedback
and status
. We can see from the brand_feedback
parameter that TAX_ID
is the issue. Looking at our glossary above, this means a mismatch between the entered tax identification number with the business information. That does not necessarily mean that the tax ID itself is wrong; instead, it could mean that the business name does not match.
At this point you should verify the business name, address, and tax ID to make sure that they all match. To verify this you could ask your customer, or use a service like TIN check (not an official Twilio partner, but we've heard it's useful!).
Let's say it's determined that the tax ID was the issue. To fix it we'll have to update the customer_profile_business_information
EndUser
object. Read more about updating EndUser objects in the TrustHub API documentation.
Update the EndUser’s tax ID attribute:
ATTRIBUTES=$(cat << EOF
{
"business_registration_number": "352618029"
}
EOF
)
curl -X POST https://trusthub.twilio.com/v1/EndUsers/IT23cc13be25ae2f56a240f7745ecbd5f4 \
--data-urlencode "Attributes=$ATTRIBUTES" \
-u $DEC8_SID:$DEC8_TKN | json_pp
Once you've finished making edits, it is essential to place your Business Profile and A2P Profile back into review state. Brand resubmission cannot proceed without this.
Request to resubmit the Secondary Business Profile to review state:
curl -X POST https://trusthub.twilio.com/v1/CustomerProfiles/BUb4784f724e5b12f319296cf6fc521eeb \
--data-urlencode "Status=pending-review" \
-u $DEC8_SID:$DEC8_TKN | json_pp
Request to resubmit the A2P Messaging Profile to review state:
curl -X POST https://trusthub.twilio.com/v1/CustomerProfiles/BUced9020cecf2910329dcab95938d7237 \
--data-urlencode "Status=pending-review" \
-u $DEC8_SID:$DEC8_TKN | json_pp
With the profile updated to have the correct EIN, you can make an empty POST request to the original Brand to have it resubmitted.
Request:
curl -X POST https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN1acce9e78c899aa0127200e00cd5cca7 \
-u $DEC8_SID:$DEC8_TKN | json_pp
The response to this request kicks off an asynchronous process to re-register. Note that the response will tell you the status is FAILED
because at that moment in time it is true. Wait a few minutes and check with a GET request until you have a status
of APPROVED
. That's it!
Editing brands allows you to correct information without having to incur extra fees and clutter your Twilio account.
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.