A2P Mock Brand and Campaign API
New to US A2P 10DLC registration? Please see "What is A2P 10DLC?" (support article) for more information.
The US App to Person (A2P) 10DLC Mock Brand and Campaign API allows you to develop and test applications against Twilio’s A2P Brand and Campaign APIs without incurring any A2P 10DLC related fees. Mock brands and mock campaigns are created similarly to brands and campaigns registered against the non-mock A2P APIs; however, there are some important restrictions and considerations to keep in mind when you’re using this API.
This guide will cover:
- The prerequisites needed to get started with the Mock Brand API.
- Creating mock brands.
- Creating mock A2P SMS campaign use cases.
- Deleting mock A2P SMS campaign use cases.
- Mocking brand registration scenarios
- Important considerations for mock brands and mock campaigns.
Prerequisites
Before you can start testing against the Mock Brand API you will need to create a real (non-mock) customer profile and complete all steps before Step 3, "Create an A2P Brand" in one of the two Independent Software Vendor (ISV) API walkthroughs.
For the registration process for a Standard brand, see the ISV Standard API walkthrough.
For the registration process for a Low Volume Standard brand, see the ISV Starter API walkthrough.
Not sure which brand type you should register your customers for? Head over to the ISV Starter Overview guide for a detailed look at the differences between the two brand types.
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.
Creating Mock Brands
After successfully creating a Customer Profile and linking it to an A2P messaging profile, you’re ready to create a mock brand. To do so, you will make a POST request to the Brand Registrations API and pass the mock
parameter set to True
in the request body. Mock brand creation occurs during Step 3, "Create an A2P Brand" of the ISV Starter walkthrough (as well as the Standard walkthrough).
Parameter | Valid Values | Description |
mock |
"True" "False" |
Will default to False and create a real brand if not supplied, or does not equal True . |
Note the response for this request. You will see the mock
parameter with the boolean value true
upon successful creation of a mock brand. If you don’t pass mock
your brand will be created as a real (non-mock) brand, incurring A2P 10DLC fees and billing events where applicable.
Creating Mock Campaigns
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.
Please Note: We highly discourage the use of existing Messaging Services with Senders in the Sender Pool to avoid any risks of your US messages failing.
We encourage the creation of a new Messaging Service without any Senders to test the creation of Mock Campaigns.
Prior to creating a mock campaign, you will need a Messaging Service to associate with the mock campaign. To do that, please see Step 4 "Create a Messaging Service" in the ISV Starter API walkthrough.
Once you’ve created your mock brand and a Messaging Service, you can create associated mock A2P SMS campaign use cases. An A2P SMS campaign use case represents a messaging use case or the intent of the messages you wish to send (for example: marketing or account notifications).
Mock campaigns can only be created from mock brands, and they inherit the mock
parameter from that mock brand.
In the response for this request you will see the mock
parameter with the boolean value true
indicating that this campaign was created from a mock brand, making it a mock campaign.
Please note that you must pass True
for the mock attribute when creating your mock brand in order to create a mock campaign use case.
Deleting Mock Campaigns
Once you are finished testing your mock campaign, you can delete it from your Messaging Service with the US A2P Compliance resource identifier QE2c6890da8086d771620e9b13fadeba0b
. You can then add a new campaign with a non-mock brand to start sending A2P messaging traffic from the Messsaging Service.
Mocking Brand Registration Scenarios
The Mock Brand API supports Mock Brand EINs for mock Standard Brands. EIN (Employee Identification Number) is the preferred tax ID for US based Twilio customers. The generic term for EIN is "business registration number" or "tax ID".
You can pass a mock EIN value during customer profile creation so that you can control brand characteristics that are key to qualifying for certain campaign use cases. While creating your mock Brand, the mock EIN will be passed in Step 1.3 of the ISV Standard API Walkthrough as the value of the business_registration_number
.
Depending on a brand’s entity type, you can get different results for your testing by using specific Brand EINs. Your entity type is passed as part of the A2P Trust Bundle you create in Step 2 of the ISV API walkthrough.
The entity types that support mock EINs are:
PRIVATE_PROFIT
NON_PROFIT
PUBLIC_PROFIT
GOVERNMENT
Each entity type supports up to 100 different VERIFIED
brands and 100 different UNVERIFIED
brands, based on the following mock EIN conventions:
- Mock Brand EINs matching the pattern 0000000XX will be successfully verified during brand registration.
- Mock Brand EINs matching the pattern 00000001XX will not be verified during brand registration.
Recognized List of Mock EINs
Below is a list of predefined mock EINs that you can use to test various brand registration scenarios for the supported different entity types.
You will notice information regarding the brand_feedback
parameter in the mock EIN description column for the UNVERIFIED
identity status. This field is returned in the response of Creating or Fetching an A2P Brand and will give you a descriptive recommendation for ways to fix your brand registration.
When you select your entity type as NON_PROFIT:
Mock EIN |
Identity Status |
Description |
000000001 |
VERIFIED |
501(c)(3) |
000000002 |
VERIFIED |
501(c)(4) |
000000003 |
VERIFIED |
501(c)(5) |
000000004 |
VERIFIED |
501(c)(6) |
000000100 |
UNVERIFIED |
Unverified brand. |
000000101 |
UNVERIFIED |
Unverified brand. |
Private-Profit
When you select your entity type as private-profit:
Mock EIN |
Identity Status |
Description |
000000000 |
VERIFIED |
Verified Brand. |
000000100 |
UNVERIFIED |
Unverified brand. |
Public-Profit
When you select your entity type as public-profit:
Mock EIN |
Identity Status |
Description |
000000000 |
VERIFIED |
Verified Brand. |
000000100 |
UNVERIFIED |
Unverified brand. |
000000101 |
UNVERIFIED |
Unverified brand. |
Government
When you select your entity type as government:
Mock EIN |
Identity Status |
Description |
000000000 |
VERIFIED |
Verified Brand. |
000000100 |
UNVERIFIED |
Unverified brand. |
000000101 |
UNVERIFIED |
Unverified brand. brand_feedback parameter will return feedback ID |
Mock EINs for 527 Political Organizations
527 Political organizations must import a Campaign Verify token (CV token) in order to unlock the "Political" Special Use Case. To mock this scenario you will need to do the following:
- During Step 1.3 of the ISV Standard API Walkthrough, you will pass the mock EIN 000000100 as the value of your
business_registration_number
. - CV tokens cannot be mocked, so you will need to request test CV tokens from Campaign Verify in order to import them and unlock status as a recognized 527 Political Organization.
For more information on Campaign Verify and the verification process you will complete as a 527 Political Organization, please see the ISV Onboarding Guide.
Important Considerations
It’s important to note that the Mock Brand API is strictly for development purposes and the mock brands and campaigns you create are not functional for sending live A2P traffic. Below are some important considerations to keep in mind as you work with this API:
- Mock Brands and campaigns expire after 30 days. After the 30 day period, your mock brand will become invalid and expire.
- You cannot delete a mock brand. You must wait until the mock brand expires. Mock Campaigns can be deleted as described above.
- There are no billing events from mock brand or mock campaign creation.
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.