A2P Mock Brand and Campaign API

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.

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).

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

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:

When you select your entity type as private-profit:

When you select your entity type as public-profit:

When you select your entity type as 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.