Menu

Expand
Rate this page:

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:

  1. The prerequisites needed to get started with the Mock Brand API.
  2. Creating mock brands.
  3. Creating mock A2P SMS campaign use cases.
  4. Deleting mock A2P SMS campaign use cases.
  5. Mocking brand registration scenarios
  6. 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.

Loading Code Sample...
        
        

        Create a mock Starter brand

        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.

        Loading Code Sample...
              
              

              Create a mock Starter campaign

              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.

              Loading Code Sample...
                    
                    

                    Delete a mock Starter campaign

                    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.

                    Non-Profit

                    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. brand_feedback parameter will return feedback IDs TAX_ID and NONPROFIT.

                    000000101

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback IDs TAX_ID and NONPROFIT.

                    Private-Profit

                    When you select your entity type as private-profit:

                    Mock EIN

                    Identity Status

                    Description

                    000000000

                    VERIFIED

                    Verified Brand.

                    000000100

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback ID TAX_ID.

                    Public-Profit

                    When you select your entity type as public-profit:

                    Mock EIN

                    Identity Status

                    Description

                    000000000

                    VERIFIED

                    Verified Brand.

                    000000100

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback IDs TAX_ID and STOCK_SYMBOL.

                    000000101

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback ID STOCK_SYMBOL.

                    Government

                    When you select your entity type as government:

                    Mock EIN

                    Identity Status

                    Description

                    000000000

                    VERIFIED

                    Verified Brand.

                    000000100

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback IDs TAX_ID and GOVERNMENT.

                    000000101

                    UNVERIFIED

                    Unverified brand. brand_feedback parameter will return feedback ID GOVERNMENT.

                    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:

                    1. 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.
                    2. 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.

                    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.

                    Loading Code Sample...
                          
                          
                          

                          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