Menu

Expand
Rate this page:

ISV A2P 10DLC Standard and Low-Volume Standard Registration: API Walkthrough

Please rate limit all API requests for Brand and Campaign registration to 1 request per second.

The process for registering for a Low Volume Standard Brand is the same as registering for a regular Standard Brand, with the only exception that Low Volume Standard Brands must skip secondary vetting when creating an A2P Brand (skip_automatic_sec_vet should be True when you create an A2P Brand). For more on Standard vs Low-Volume Standard see Section 3 below.

Purpose of this Guide

  • intended for ISVs
  • registering secondary clients
  • for Standard or Low-Volume Standard A2P Brands and Campaigns
  • using Twilio's API tools

This guide is a step-by-step walkthrough of the various API calls that an ISV will make to register their secondary customers for A2P 10DLC capabilities using Twilio APIs. This guide is intended for ISVs only--that is, businesses that resell Twilio messaging services to their own customers (who from Twilio's perspective are known as secondary customers). For example, if you are a software company providing a platform for your customers to send sms messages on their own behalf, powered by Twilio's messaging services, you are an ISV.

If you instead need to register for A2P 10DLC capabilities to send sms messages exclusively on your own behalf, you are a direct customer, and would not typically use the following API calls for A2P registration. Instead, you would use the Twilio Console tool for registration, and would follow this guide if you are registering as a Standard or Low-Volume Standard Brand, or this guide if you are registering as a Sole Proprietor Brand.

Please note that Standard and Low-Volume Standard Brands must have an EIN or other national Tax ID in order to register, while Sole Proprietor Brands cannot have such a Tax ID (and must also be headquartered in the U.S. or Canada).

In this guide you will be registering your secondary customers' brands as either Standard or Low-Volume Standard Brands (see Section 3 below for the difference between the two). If you instead need to register your secondary customers for Sole Proprietor Brands, please see this guide instead.

While our A2P registration Console tool is intended primarily for use by direct customers, and the API calls covered in this guide are intended for use by ISVs, the Console can also be used for ISVs to register their secondary customers, though this is necessarily a one-at-a-time process (while the API calls can be used for batch-submission processes, or as the back-end for your own customer self-service registration websites). As an ISV, you might consider using the Console tool to register one or two of your secondary customer brands simply as a way to familiarize yourself with the basic steps in the registration process and the inputs required at each step, before using this document's API sequence for your other customers. From the standpoint of Twilio and A2P ecosystem partners, registrations are identical whether they originate in the Console or API calls. The Console can also be a convenient way to check on the status of particular Brand and Campaign registrations.

You will be working with two different APIs to cover the three main steps of this registration process:

  • Customer Profile and Trust Bundle registration -- Trust Hub API
  • Brand registration -- Messaging API
  • Campaign creation -- Messaging API

If you haven't already done so, be sure you're using the latest version of the Twilio Helper Libraries to perform the API calls in this walkthrough.

Prerequisite: Create a Trust Hub Profile for your Company (ISV)

What does this do? Creates a Trust Hub profile for your business (the ISV).

Which API? This can only be done via the Trust Hub UI in the Twilio Console.

Before proceeding with the onboarding process for your clients, all ISVs must have a primary customer profile in an APPROVED state. You can do this in the Trust Hub, located in the Twilio Console. In order to register secondary profiles, the primary customer profile needs to have “ISV Reseller or Partner” selected as your Business Identity.

NOTE: To get the highest possible messaging limits, please create your customer's profile with details that exactly match those in their US EIN listing (or that of their relevant national Tax ID if their business is located outside the U.S.). If there are any differences – for example, in the business name or address – their messaging limits will be lower. Please have your customer verify these details via their W2 form or equivalent national tax record.

Tip: Copy the Primary Customer Profile's bundle SID (BUxxx) from Customer Profile Details page to be used in a later step; see https://console.twilio.com/us1/account/trust-hub/customer-profiles > View profile details button

1. Create secondary customer profile(s) and attach required information

Before you go through the process described in this step, be aware that the secondary customer profile you are creating here can be used as well for three Twilio Voice products: SHAKEN/STIR Trusted Calling, Branded Calls, and CNAM Registration. See the Trust Hub console for details on each of these products. If your secondary client is already using any of these Voice products, this means that a customer profile identical to the one you are about to create has already been created for that customer and accepted by Twilio. Rather than creating a new one, then, you should go to the Trust Hub Console (Trust Hub > Customer Profiles), and beneath your own primary ISV business profile you will see a list of all your existing secondary customer profiles. Select the SCP corresponding to the customer you are now registering for A2P messaging, if you find it listed there, and click on its Bundle SID to inspect its details to ensure that they are still correct for this client. If so, copy the Bundle SID of that profile (begins with 'BU'). You can then skip the entirety of Step 1 of the present walkthrough, and start at the beginning of Step 2 below (there you're creating a Trust Product for that client, and the Trust Product will be specific to A2P vs the Voice products). The profile Bundle SID that you just copied will become the trust_product_sid that you use in Step 2.5.

Conversely, if you have not yet used any of these three Voice products with this secondary client, but plan to do so in the future, bear in mind that the Customer Profile you are creating in Step 1 below can itself be reused for SHAKEN/STIR, Branded Calls and/or CNAM Registration.

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.

Note: For all information entered as part of this registration process, please note that The Campaign Registry (TCR) supports all “utf8mb4” supported characters. Please see the list for all Unicode 15.0 supported scripts and characters here: https://www.unicode.org/charts/

What does this do? Creates Trust Hub profiles for each of your clients

Which API? Trust Hub API

Once you have an approved primary customer profile for your own ISV business entity, create a secondary customer profile for each of your clients. Depending on your Twilio account architecture, you may need to create the Secondary Customer Profile (SCP) at the Twilio subaccount or account level.

The following will guide you through the necessary steps to create a (single) secondary customer profile. If you have multiple secondary customers to register, you must follow the following process separately for each customer.

NOTE: For purposes of A2P registration, your ultimate objective in Sections 1-3 of this guide is to register an A2P Brand for your secondary customer. This Brand creation itself happens in Part 3. However, the success or failure of this Brand registration (and, if successful, the Trust Score which will determine allowable messaging throughput) depends to a very large extent on information you will enter in this first profile-creation step, and specifically on the information detailed in Parts 1.2 through 1.6 below. Please attend carefully to the instructions and guidance offered in these steps, to maximize your chances of successful Brand registration with the highest possible Trust Score.

Conversely, if your Brand registration does fail, or results in a lower Trust Score than you feel is warranted, it is generally this customer profile information that will need to be rectified. In other words, some information in the customer profile you are creating in this step would need to be updated (as well as the Trust Product you will create in Step 2), before the Brand itself can be resubmitted.

1.1 Fetch the Secondary Customer Profile Policy

This step requires you to use a hard-coded PolicySID: RNdfbf3fae0e1107f8aded0e7cead80bf5. As the Trust Hub is built to support multiple use cases, the PolicySID is the object that Twilio uses to store the various policies and regulations for that specific trust product. You will see this reappear later on for A2P 10DLC regulations.

Loading Code Sample...
        
        

        Fetch the Secondary Customer Profile Policy

        1.2 Create an empty secondary customer profile bundle

        In this step, you are populating the information for a customer profile, similar to what you did when you filled in your own Primary Customer Profile in the Twilio Console.

        Secondary Customer Profiles can live at either the parent or subaccount levels. If you are creating these within a subaccount, the AccountSID and AuthToken that you use in the following requests should be that of the Subaccount.

        This API call to the customer_profiles endpoint involves the following parameters:

        Parameter Details
        policy_sid The static Trust Hub policy identifier for secondary customer profiles for A2P purposes. The hard-coded value is RNdfbf3fae0e1107f8aded0e7cead80bf5 and you use this value for every Secondary Customer Profile Bundle you create.
        friendly_name A string representing your customer's business name. This is an internal name meant for you to identify this particular customer profile Bundle for your customer.
        email A string representing your customer's email address. This must be a valid email address and will be verified by TCR.
        status_callback (optional)

        Provides a status callback URL. If provided, all status callbacks with bundle information in this and following steps will be sent to the provided URL.

        Loading Code Sample...
              
              

              Create an empty secondary customer profile bundle

              1.3 Create end-user object of type: customer_profile_business_information

              This step provides Trust Hub with necessary information about the customer/business that is represented by the secondary customer profile.

              If your customer is a US entity with an EIN, use this EIN to register their customer profile. Do not use a DUNS number. If your customer is a non-US based entity, you should use the Tax ID with which they are registered with their national tax authority (Refer to the business_registration_identifier list in the table below for some specific international Tax IDs).

              Only the Parent Business Profile should be marked as isv_reseller_or_partnerin most scenarios, so please pass direct_customer for the business_identity field in this step for Secondary Customer Profile registrations

              In this step, you will make a create call to the end_user endpoint of the Trust Hub API.

              • You will pass in a type parameter of "customer_profile_business_information", to indicate the operation you are performing in this particular step.
              • The friendly_name parameter allows you to name the object you are creating here, to associate it with the secondary brand. For internal use only.
              • As shown in the code snippet, all of the specific business information is passed in within the attributes parameter, as an object. The following table specifies each attribute relevant to this use case, and provides all possible valid values for each attribute. Please refer to the language-specific code snippets for the appropriate syntax/formatting of the attributes object in each language.

              Note: Because this will be a Standard or Low-Volume-Standard registration, "Sole Proprietorship" is not a valid value for business_type in this case. If your secondary customer is a U.S.-based LLC of a type considered "Sole Proprietorship" by the IRS, The Campaign Registry still views this customer as eligible only for a Standard or Low-Volume Standard Brand because, as an LLC, that customer uses an EIN for tax purposes. In this case you would specify Limited Liability Corporation as the business_type.

              For business_industry, please choose the industry that most closely resembles the business in question.

              Attribute Valid values
              business_name
              • If you're registering a US entity, please enter the exact legal business name as registered with the EIN, which can be found on the CP 575 EIN Confirmation Letter. An exact match between the legal business name and the EIN as displayed on CP 575 is required for the Brand to be successfully registered.
              • Please do not use the legal business name found on the W2 or W9 forms as they may be different from what you have on the CP 575 notice. If you've misplaced your CP 575 notice, you may request a 147c letter from the IRS and use the information there for registration.
              • Please note that your full legal business name may span multiple lines on your CP 575 / 147c letter. If that is the case, you must input all the lines above the address line (which constitutes your full legal business name) instead of just using the first line.
              website_url

              This is the website of the business entity whose brand you are registering. If you are an ISV, this is the website of the secondary customer's brand, NOT the website of your own business. This website must be functional, and it must bear some obvious relationship with the business name you have entered above.

              • As part of our compliance review, we conduct automated checks on the URLs provided during campaign and brand registration. Our system captures a public-facing screenshot, and evaluates it against compliance rules, which can be found here. This compliance check is a mandatory step in our registration process. If you have any questions or concerns about the process, please contact our support team.
              business_type

              Partnership

              Limited Liability Corporation

              Co-operative

              Non-profit Corporation

              Corporation

              business_industry

              AUTOMOTIVE

              AGRICULTURE

              BANKING

              CONSTRUCTION

              CONSUMER

              EDUCATION

              ENGINEERING

              ENERGY

              OIL_AND_GAS

              FAST_MOVING_CONSUMER_GOODS

              FINANCIAL

              FINTECH

              FOOD_AND_BEVERAGE

              GOVERNMENT

              HEALTHCARE

              HOSPITALITY

              INSURANCE

              LEGAL

              MANUFACTURING

              MEDIA

              ONLINE

              PROFESSIONAL_SERVICES

              RAW_MATERIALS

              REAL_ESTATE

              RELIGION

              RETAIL

              JEWELRY

              TECHNOLOGY

              TELECOMMUNICATIONS

              TRANSPORTATION

              TRAVEL

              ELECTRONICS

              NOT_FOR_PROFIT

              business_registration_identifier

              EIN USA: Employer Identification Number (EIN)

              DUNS USA: DUNS Number (Dun & Bradstreet) [NOTE: If your customer has a US entity or an International Tax ID, use EIN to register their customer profile to avoid brand registration failures. Do not use a DUNS number.]

              CBN Canada: Canadian Business Number (first 9 digits only)

              • NOTE: as of July 27th we only accept Canadian Business Number (identified in this field as CBN); we no longer accept Canadian Corporation Number as business_registration_identifier here or business_registration_number below.

              CN Great Britain: Company Number

              ACN Australia: Company Number from ASIC (ACN)

              CIN India: Corporate Identity Number

              VAT Estonia: VAT Number

              VATRN Romania: VAT Registration Number

              RN Israel: Registration Number

              Other Other

              business_identity

              direct_customer

              Note: The business_identity column accepts values including direct_customer, isv_reseller_or_partner, unknown. However, when you're setting up a secondary profile for your customer, please make sure to use direct_customer for this field.

              business_regions_of_operation

              AFRICA

              ASIA

              EUROPE

              LATIN_AMERICA

              USA_AND_CANADA

              business_registration_number

              The value here depends on which business_registration_identifier you indicated above, e.g.:

              US EIN: [xx-xxxxxxx] (NUMERICAL)

              US DUNS: [xx-xxx-xxxx] (NUMERICAL)

              CA CBN: [xxxxxxxxx] (NUMERICAL)

              UK Company Number

              AUS ACN

              IN CIN

              EE VAT

              RO VAT

              Loading Code Sample...
                    
                    

                    Create end-user object of type: customer_profile_business_information

                    1.4 Create end-user of type: authorized_representative_1

                    This step provides required information about an authorized business representative (one authorized point of contact is required) for the secondary customer profile.

                    You should use a point of contact from the end business (secondary client) representing this brand, not from your own business. At this time, Twilio or The Campaign Registry does not use this contact information to reach out to the end business. If in the future the industry requirements change and there becomes a need for the ecosystem to reach out to this contact information for verification, there may be a change in this policy.

                    This step makes another create call to the end_users API endpoint, but this time the type parameter has the value of "authorized_representative_1." The friendly_name attribute might be something like "auth_rep_1". As in the previous step, the actual information on this point of contact is passed in via the attributes parameter, as an object. The following table lists the attributes and valid values:

                    Attribute Valid values
                    business_title

                    Represents the exact job title of the contact, and is free form.

                    job_position

                    Director

                    GM

                    VP

                    CEO

                    CFO

                    General Counsel

                    Other

                    last_name

                    Exact last name of the contact

                    phone_number

                    Valid phone number for this contact

                    first_name

                    Exact first name of this contact

                    email

                    Valid email for this contact

                    Loading Code Sample...
                          
                          

                          Create end-user of type: authorized_representative_1

                          1.5 Create end-user of type: authorized_representative_2 (optional)

                          This step provides optional information about a second authorized business representative for the secondary customer profile. This is another create call to end_users, with a type of "authorized_representative_2". If you do choose to list a second authorized representative, please use the same attribute fields listed for 1.4 above, with the values adjusted accordingly.

                          Loading Code Sample...
                                
                                

                                Create end-user of type: authorized_representative_2 (optional)

                                1.6 Create supporting document: customer_profile_address

                                This step creates an object representing your customer’s address information if you don’t already have one for the customer. Alternatively, if you already have an address, skip to the next code block, where you can create a customer document (when you have a valid AddressSID).

                                The following table lists all parameters for this API call and their valid values:

                                Parameter Valid values
                                customer_name The full name to associate with the new address
                                street The number and street address of the new address
                                city

                                The city of the new address

                                region

                                Any correct two-letter abbreviation for a US state, for example: "NY" or "WA"

                                postal_code The postal code of the new address
                                iso_country The ISO country code of the new address
                                friendly_name (optional) A descriptive string that you create to describe the new address. It can be up to 64 characters long.
                                emergency_enabled (optional) Whether to enable emergency calling on the new address. Can be: `true` or `false`. Default is 'false'.
                                auto_correct_address (optional) Whether we should automatically correct the address. Can be: `true` or `false` and the default is `true`. If empty or `true`, we will correct the address you provide if necessary. If `false`, we won't alter the address you provide.
                                street_secondary (optional) Additional address information, if necessary (e.g. "Suite" or "Attention")

                                Loading Code Sample...
                                      
                                      

                                      Create supporting document: customer_profile_address

                                      1.6.1 Create customer document (when you have a valid AddressSID)

                                      In this step you will make a call to the supporting_document API endpoint, with a type parameter value of "customer_profile_address".

                                      • The friendly_name parameter value should remind you of the relevant customer profile, e.g. "acme" in our example.
                                      • As shown in the code snippet, the attributes parameter value in this case contains a single name/value pair: address_sids:, and then a valid AddressSID that you either derived (as the SID output parameter) from the previous call in 1.6, or had already from some earlier customer_profile_address creation with the same address data. In either case, this AddressSID will associate that set of address data, enumerated in step 1.6, with the secondary customer profile you are creating in this general step.

                                      Note: The creation of a secondary customer profile does not depend on the status of a supporting document. The status field of the JSON response in this step can be disregarded.

                                      Loading Code Sample...
                                            
                                            

                                            Create customer document

                                            1.7 Assign end-users, supporting document, and primary customer profile to the empty secondary customer profile that you created

                                            Using the SIDs you've gotten in the json response from each of the steps above, you will now attach them all to the secondary customer profile. This will entail four (or five, if you've chosen to specify a second authorized_representative) separate create calls to the customer_profiles endpoint. In each case the customer_profiles value is the SID of the empty secondary profile itself, which was the first entity created in this general step, and the object_sid is the relevant SID returned from the API calls for items 1-4 below (or rather 1-3, whereas in #4 the SID comes from the primary customer profile under which this SCP is being created). Again, the code snippet below represents an example of only one of these four (or potentially five) calls:

                                            1. authorized_representative_1 and optionally authorized_representative_2
                                            2. supporting document (address)
                                            3. customer_profile_business_information
                                            4. primary_customer_profile

                                            Loading Code Sample...
                                                  
                                                  

                                                  Assign end-users, supporting document, and primary customer profile to the empty secondary customer profile that you created

                                                  1.8 Run evaluation on secondary customer profile

                                                  By running an evaluation, you check that you’ve provided all the required Secondary Customer Profile information. The evaluation also flags issues with the data before you submit it to Twilio’s Trust Hub. If there are no errors, you will get a status of "compliant", otherwise it will fail and error codes will be surfaced to you.

                                                  This call to the customer_profile_evaluation API endpoint takes two parameters:

                                                  Parameter Valid values
                                                  customer_profile_sid The SID of the secondary customer profile you created above
                                                  policy_sid The hard-coded policy SID associated with the creation of a secondary customer profile: RNdfbf3fae0e1107f8aded0e7cead80bf5

                                                  Loading Code Sample...
                                                        
                                                        

                                                        Run evaluation on secondary customer profile

                                                        1.9 Submit the secondary customer profile for review

                                                        This will submit the secondary customer profile, including all of the bundled information, to Twilio Trust Hub for review. You can proceed to the next steps without an approved secondary customer profile.

                                                        This submission is accomplished by way of an update call to the customer_profile API endpoint, for which you called the create method in step 1.2 above. Here are the required and optional parameters for this particular step:

                                                        Parameter Valid values
                                                        sid The SID of the secondary customer profile you created above
                                                        status Other than specifying the profile SID itself, the one required action for this step is to change the status of this profile to a value of pending_review. The result of this API call will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough.
                                                        status_callback (optional) If you did not provide a status_callback URL in step 1.2, you can provide one here. If you've provided one already, a value entered here will overwrite the existing value. See the Bundles Resource documentation for details on Twilio's request to your webhook.
                                                        friendly_name (optional) As friendly_name was a required parameter in step 1.2, you should only use this parameter in the current call if you wish to update the friendly_name
                                                        email (optional) This was a required field in step 1.2, so you should only use this parameter if you wish to change the email address you entered previously.

                                                        You do not need to wait for this Secondary Customer Profile to have a status of approved before moving on to Brand submission in step 3. Brand submission will retroactively modify your Secondary Customer Profile’s status.

                                                        Loading Code Sample...
                                                              
                                                              

                                                              Submit the secondary customer profile for review

                                                              2. Create an A2P Trust Product

                                                              What does this do? Creates an A2P Profile (a bundle of information) that you will submit with your Customer Profile to the Campaign Registry

                                                              Which API? The Trust Hub API

                                                              Once your Secondary Customer Profile from the previous step is in_review, you can create a new Standard A2P Trust Bundle for your customer, which you will then use to complete a Standard or Low-Volume Standard Brand. The steps in this section are similar to the ones you completed in Section 1, but you will provide different information about your customer here. These steps are required before this new profile can be submitted to The Campaign Registry (TCR) for approval.

                                                              2.1 Fetch A2P Profile Policy

                                                              Fetch the policy details for A2P Messaging.

                                                              This is a fetch/GET call to the policies endpoint of the Trust Hub API. The one required pameter is sid, which will be the hardcoded Regulation SID RNb0d4771c2c98518d916a3d4cd70a8f8b

                                                              See the code snippet below:

                                                              Loading Code Sample...
                                                                    
                                                                    

                                                                    Fetch A2P Profile Policy

                                                                    2.2 Create an empty A2P Trust Bundle

                                                                    This Standard A2P Trust Bundle contains additional information about your customer (from the profile you created above) and their Brand. You fill out some of the fields now, and attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 2 of this walkthrough.

                                                                    These are the parameters for the API request to create a Standard secondary client A2P Trust Bundle (this is a create call to the trust_products API endpoint):

                                                                    Parameter Valid Values
                                                                    friendly_name A string representing your customer's business name. This is an internal name for you to identify this Bundle for your customer. Can be the same as the friendly_name you set up for the secondary customer profile in steps above.
                                                                    email A string representing your customer's email address
                                                                    policy_sid The static A2P Messaging TrustHub Policy identifier. The hard-coded value is RNb0d4771c2c98518d916a3d4cd70a8f8b.
                                                                    status_callback (optional) The URL at which you would like to receive status update webhook requests for this Trust Bundle.

                                                                    Loading Code Sample...
                                                                          
                                                                          

                                                                          Create an empty A2P Trust Bundle

                                                                          2.3.1 Create an end user of type us_a2p_messaging_profile_information (public companies)

                                                                          This step is similar to step 1.3 above, in that you are once again making a create call to the end_user endpoint. But this time:

                                                                          1) for the type parameter you are passing in a value of us_a2p_messaging_profile_information

                                                                          2) for the friendly_name parameter you would want a name that references this step, such as "A2P for acme-inc" (OR "A2P for nonprofit-acme-inc" or "A2P for government-acme-inc", see next)

                                                                          3) in the attributes parameter you are once again passing in an object of name/value pairs, but this time it's a smaller and different list of values. Also, importantly, the essential attribute company_type will differ, depending on what type of client company you are registering. There will be more or fewer accompanying attributes depending on this type. Accordingly, we have provided four different code snippets, corresponding to the typical registrations for public companies (immediately below), private companies (2.3.2 below), nonprofit entities (2.3.3), and governmental entities (2.3.4).

                                                                          NOTE that the general use case for this document is the creation of Standard or Low-Volume Standard Brands and Campaigns. Thus the company_type of Sole Proprietor is not valid for this use case, as that would be the type appropriate for a Sole Proprietor brand registration.

                                                                          Because this first example call is for a public (for-profit) company, in addition to specifying a company_type attribute of public, you will also specify the stock_exchange on which that company's stock is listed, as well as its stock_ticker symbol. These latter attributes would not apply to the three organization types addressed in the examples that follow.

                                                                          Loading Code Sample...
                                                                                
                                                                                

                                                                                Create an end user of type us_a2p_messaging_profile_information (public companies)

                                                                                2.3.2 Create an end user of type us_a2p_messaging_profile_information (private companies)

                                                                                This is the variant of step 2.3 that will apply to private companies (i.e., not publicly-traded) that are still formally corporations AND have EINs. If your secondary client does not have an EIN, and does business in the US, they probably qualify for a Sole-Proprietor Brand and should be registered as such.

                                                                                Note that because this case pertains to a private company, within the attributes parameter of this call, company_type is set to private, and there is no stock-exchange information as in 2.3.1 above.

                                                                                Loading Code Sample...
                                                                                      
                                                                                      

                                                                                      Create an end user of type us_a2p_messaging_profile_information (private companies)

                                                                                      2.3.3 Create an end user of type us_a2p_messaging_profile_information (nonprofit)

                                                                                      This variant of step 2.3 pertains to non-profit organizations. Creating a brand with a company_type of non_profit (as shown here) is essential to unlocking campaign special use cases reserved for particular types of nonprofits. For instance, 501(c)(3)s can only unlock the Charity special use case if their brand is created with a non-profit company type here — this triggers TCR to verify the brand's 501(c)(3) status and, upon success, marks them as qualified for this use case.

                                                                                      Loading Code Sample...
                                                                                            
                                                                                            

                                                                                            Create an end user of type us_a2p_messaging_profile_information (nonprofit)

                                                                                            2.3.4 Create an end user of type us_a2p_messaging_profile_information (government)

                                                                                            This final variant of step 2.3 pertains to governmental organizations or agencies. Creating a brand with a company_type of government (as shown here) is essential to unlocking increased messaging throughput reserved for government agencies. Creating a brand with the government company type here triggers TCR to verify the brand's status as a government entity and, upon success, qualifies the brand for increased throughput (T-Mobile: Unlimited daily cap, AT&T: TBD MPS).

                                                                                            Loading Code Sample...
                                                                                                  
                                                                                                  

                                                                                                  Create an end user of type us_a2p_messaging_profile_information (government)

                                                                                                  2.4 Assign the end user to the A2P Trust Bundle

                                                                                                  In this step, you will associate the end user object you just created in step 2.3 with the A2P Trust Bundle you created in step 2.2. In this create call to the trust_products_entity_assignments endpoint, the Path or trust_product_sid is the SID returned in step 2.2 (it will begin with "BU"), and the object_sid parameter is the SID (beginning with "IT") that was returned in step 2.3.1, 2.3.2, 2.3.3 or 2.3.4, depending on the company_type of the Brand you're creating.

                                                                                                  Loading Code Sample...
                                                                                                        
                                                                                                        

                                                                                                        Assign the end user to the A2P Trust Bundle

                                                                                                        2.5 Assign secondary customer profile bundle to A2P trust bundle

                                                                                                        This step ties your A2P trust bundle back to the secondary customer profile you created in step 1 above. This is another create call to the trust_products_entity_assignments endpoint. The Path or trust_product_sid is once again the SID returned in step 2.2 (it will begin with "BU"), and the object_sid parameter in this case is the SID for the secondary client profile you created in step 1 above.

                                                                                                        Loading Code Sample...
                                                                                                              
                                                                                                              

                                                                                                              Assign secondary customer profile bundle to A2P trust bundle

                                                                                                              2.6 Run evaluation on A2P Trust Product

                                                                                                              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.

                                                                                                              In this create call to the trust_products_evaluations endpoint, the trust_product_sid is the same one you used in 2.4 and 2.5 (begins with "BU"), while policy_sid is the hardcoded policy SID from step 2.1: RNb0d4771c2c98518d916a3d4cd70a8f8b

                                                                                                              The status parameter in the response to this call will either be compliant or noncompliant.

                                                                                                              Loading Code Sample...
                                                                                                                    
                                                                                                                    

                                                                                                                    Run evaluation on A2P Trust Product

                                                                                                                    2.7 Submit A2P Trust Bundle for review

                                                                                                                    This is an update call to the trust_products endpoint, with the following possible parameters:

                                                                                                                    Parameter Valid values
                                                                                                                    sid The SID of the Trust Bundle you have created above
                                                                                                                    status Other than specifying the Trust Bundle SID itself, the one required action for this step is to change the status of this Trust Bundle to a value of pending_review. This will trigger the automated validation by our system.
                                                                                                                    status_callback (optional) If you did not provide a status_callback URL in step 2.2 you can provide one here. If you've provided one already, a value entered here will overwrite the existing value. See the Bundles Resource documentation for details on Twilio's request to your webhook.
                                                                                                                    friendly_name (optional) As friendly_name was a required parameter in step 2.2, you should only use this parameter in the current call if you wish to update the friendly_name
                                                                                                                    email (optional) As this was a required field in step 2.2, you should only use this parameter if you wish to change the email address you entered previously.

                                                                                                                    You do not need to wait for this A2P Trust Bundle to be approved before moving on to Brand submission in step 3. Brand submission will retroactively modify your A2P Trust Bundle's status.

                                                                                                                    Loading Code Sample...
                                                                                                                          
                                                                                                                          

                                                                                                                          Submit A2P Trust Bundle for review

                                                                                                                          3. Create an A2P Brand

                                                                                                                          What does this do? Submits the combined package of your A2P Messaging Profile and Customer Profile to the Campaign Registry (TCR) in order to get the A2P Brand registered. TCR is the 3rd-party body that must approve the provided information in both profiles in order for your Brand registration to be registered successfully.

                                                                                                                          Which API? The Messaging API

                                                                                                                          Note: The most important decision during this Brand-creation step is whether you want to register as a Standard or Low-Volume Standard Brand. The latter creation step is identical to the former except that Secondary Vetting is skipped, by setting the parameter skip_automatic_set_vet to true in the following call, so that the Brand being submitted for registration will only go through primary vetting and skip secondary vetting. This reduces Brand registration cost; however, please note that daily message caps and throughput may be significantly lower for Brands registered without Secondary Vetting (hence the name "Low Volume Standard").

                                                                                                                          For more details on the approach you should choose, see our support article Secondary Vetting for A2P 10DLC.

                                                                                                                          Low Volume Standard Brands will by default receive the following throughput and messaging limits:

                                                                                                                          Brand is a Russell 3000 index company? T-Mobile daily message limit (SMS segments + MMS) Message throughput tier – Declared use case Message throughput tier – Mixed/Marketing use case Message throughput tier - Low volume mixed use case
                                                                                                                          Yes 200,000 75 MPS per major US carrier 75 MPS per major US carrier 1.25 MPS per major US carrier
                                                                                                                          No 2,000 4 MPS per major US carrier 4 MPS per major US carrier 1.25 MPS per major US carrier

                                                                                                                          If you’ve registered a Low Volume Standard brand, and later wish to go through Secondary Vetting and receive higher throughput and messaging limits, please contact Twilio support. The Campaign Registry (TCR) charges $40 for Secondary Vetting, and this fee will be passed onto you.

                                                                                                                          For more information, please see our support article on Secondary Vetting for A2P 10DLC.

                                                                                                                          Note for 527 Political Organizations: ISVs registering 527 Political customers should in all cases pass skip_automatic_sec_vet as true when creating an A2P Brand. Secondary vetting is not required as A2P messaging limits are determined by your status as a 527 organization.

                                                                                                                          The same applies to political organizations with a Campaign Verify token as well; they should disable automated Secondary Vetting. Political organization brands will receive increased throughput when a valid Campaign Verify token is uploaded at the brand registration step. See the step below, Import Campaign verify token to an existing brand, for more information.

                                                                                                                          Note for Government entities and Non-profits: Brand registrations for non-profit and government entities should not skip automatic secondary vetting with the exception of 527 Political customers as described above. Except for 527s, secondary vetting is required to trigger automatic verification of nonprofit or government entity status by TCR and to successfully apply this status to the brand.

                                                                                                                          Brand registration entails a create call to the brand_registrations endpoint of the Messaging API. Here are the required and optional parameters for this call in the present use case:

                                                                                                                          Parameter Valid values
                                                                                                                          customer_profile_bundle_sid The SID associated with the customer profile you created in step 1.2
                                                                                                                          a2p_profile_bundle_sid The SID associated with the A2P Profile Bundle you created in step 2.2
                                                                                                                          skip_automatic_sec_vet (optional) Boolean. While this parameter is technically optional, as explained above, it is required if you are electing to create a Low-Volume Standard Brand, or have any other reason (such as 527 political organizations) to skip secondary vetting. In this case it must be set to true. Otherwise it can be set to false, or can be omitted and the value will default to false.

                                                                                                                          In the code snippet that follows, the skip_automatic_sec_vet parameter has been set to true. If your brand does need secondary vetting, set this to false or omit the parameter.

                                                                                                                          Submitting the A2P Brand triggers a billable event. By default your account will be charged $4 registration + $40 to include automated secondary vetting, unless your account currently has any vetting waivers in place or you have explicitly set skip_automatic_sec_vet to true.

                                                                                                                          Please take caution when making this API request. For more information on automated secondary vetting and associated fees, please review this support article.

                                                                                                                          A2P Brand Registration can take up to several days in some cases. If your brand isin the "IN_REVIEW" state for more than two days, please reach out to Twilio's support team.

                                                                                                                          Loading Code Sample...
                                                                                                                                
                                                                                                                                

                                                                                                                                Create an A2P Low-Volume Brand without Secondary Vetting

                                                                                                                                3.0.1 Using Fetch to check brand registration status

                                                                                                                                You can do a fetch call on this same brand_registrations endpoint to check the current status of your Brand registration, at any point after the creation step.

                                                                                                                                NOTE: it is now possible to set up and subscribe to Brand status Event Streams, so that an event message will be sent to a specified webhook url when the new Brand has been successfully registered or has failed registration. Please see this guide for setting up the necessary Event Streams sinks and event subscriptions, and for information on reading each event message payload.

                                                                                                                                As the code snippet below illustrates, the call itself requires only a path/sid to be specified, which is the Brand SID returned from the Brand creation call above. The parameters in the return json will be identical to those returned with the initial creation call, but some of the values will likely be different at a later point in time, as the status of your new Brand changes. Here are the relevant response parameters with various values and other information:

                                                                                                                                Parameter Possible values and behavior
                                                                                                                                status
                                                                                                                                • "PENDING": your Brand registration has not yet been completed. Most Brand registrations complete within a few minutes, but a few registrations take more than seven days.
                                                                                                                                • "IN_REVIEW": your Brand registration has not yet been completed; your Brand information is under manual third-party review. Such a manual review takes seven business days or more. There is no action required from your side.
                                                                                                                                • "APPROVED": your Brand registration was completed and verified. You can now register your campaigns.
                                                                                                                                • "FAILED": your Brand registration's information couldn't be verified. Please review the brand_feedback or failure_reason fields to see the error message.
                                                                                                                                • "SUSPENDED": your Brand is deemed to have potentially violated one or more rules for Brand registration established by the A2P ecosystem partners. This status will require Twilio Support assistance to address. Please see our Brand Troubleshooting Guidefor details on this status.
                                                                                                                                tcr_id
                                                                                                                                • Assigned after 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.
                                                                                                                                russell_3000
                                                                                                                                • True, if your Brand is verified to be in the Russell 3000 index (in the case of public companies)
                                                                                                                                • false
                                                                                                                                tax_exempt_status

                                                                                                                                Identifies the tax-exempt 501c status for a non-profit Brand. If you are not tax-exempt, your tax_exempt_status will be N/A. For more information see our support article the Nonprofit and Government Guide to A2P 10DLC Text Messaging

                                                                                                                                • 501c3
                                                                                                                                • 501c4
                                                                                                                                • 501c5
                                                                                                                                • 501c6
                                                                                                                                • 501c7
                                                                                                                                • 527
                                                                                                                                • N/A
                                                                                                                                skip_automatic_sec_vet
                                                                                                                                • false
                                                                                                                                • true, if you set this parameter to true in the Brand Creation step above
                                                                                                                                identity_status
                                                                                                                                • "VERIFIED": the business name and business registration number have been verified.
                                                                                                                                • "UNVERIFIED": the Brand information couldn’t be verified.
                                                                                                                                • "VETTED_VERIFIED": the secondary vetting for the Brand was successful. It has returned a brand score.
                                                                                                                                • "SELF_DECLARED": it is a Starter Brand.
                                                                                                                                government_entity
                                                                                                                                • false
                                                                                                                                • true, if your A2P Brand has been identified as a government entity.

                                                                                                                                The brand_feedback field is returned in the response of Creating/Fetching an A2P Brand. This field contains a list of Feedback IDs, where each ID corresponds to a recommendation on how you can improve your brand score. You will receive a list of feedback IDs on your brand registration, if any. Along with the list of feedback IDs, you will receive descriptive recommendations for ways to fix your brand registration.

                                                                                                                                Below are a list of possible feedback IDs that can be returned and corresponding recommendations for fixing the 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.

                                                                                                                                More than one feedback ID may be returned at a time. To understand and rectify specific Brand feedback, please see our Guide to Troubleshooting A2P Standard Brands.

                                                                                                                                You can also read more in A2P 10DLC Brand Approval Best Practices.

                                                                                                                                Loading Code Sample...
                                                                                                                                      
                                                                                                                                      

                                                                                                                                      Using Fetch to check brand registration status

                                                                                                                                      3.1 Update an A2P Brand

                                                                                                                                      You may perform a brand update a maximum of three times at no additional charge. Once you have reached this limit, reach out to Twilio Support for additional assistance.

                                                                                                                                      If you attempt a brand update more than three times, you will receive a 400 API response and a 21724 error code.

                                                                                                                                      While Twilio will continue to allow brand updates, these may incur a fee at some point in the future, as each brand resubmission entails a charge by our A2P ecosystem partners.

                                                                                                                                      What does this do? This step allows you to edit the A2P brand you've created if you have received a FAILED brand status and the tcr_id is not null. You will use the brand's SID (starting with BN) to make this update call.

                                                                                                                                      First, review the error message from the brand_feedback and feedback_reason parameters. You can use Fetch (shown above, 3.0.1) to check the feedback on your brand registration, once this becomes available. Next, you will need to perform the necessary updates using the relevant Trust Hub API endpoints. For example, you may need to update the associated customer profile or update the information attached to the listed end-user.

                                                                                                                                      Once you have finished any necessary updates to your Profile and/or Trust Bundle , use this update method of the brand_registrations endpoint to update the brand’s registration. As the following snippet indicates, the only necessary input parameter for this update call is the Brand SID (path or sid) itself. The return json will contain the same parameters you've seen in the create and fetch calls above. Remember that your newly-updated information will in many cases require manual re-verification, so allow some time for this before checking Brand Registration status again.

                                                                                                                                      As an alternative to this API call, you may review your brand feedback and update your brand via the Messaging Compliance tools in the Twilio Console. If you are registering many secondary brands and only some have failed, and potentially for different reasons, you might find it easier to keep track of your update work via the Console.

                                                                                                                                      Loading Code Sample...
                                                                                                                                            
                                                                                                                                            

                                                                                                                                            Update an A2P Brand

                                                                                                                                            3.2 Import Campaign verify token to an existing brand (527 Political Organizations)

                                                                                                                                            Prerequisites

                                                                                                                                            If you are registering a 527 political organization, we highly recommend that you review "Registration for 527 Political Organizations" in the ISV Onboarding guide for an overview of the Campaign Verify registration process and Campaign Verify tokens before completing this step.

                                                                                                                                            Note: A 527 organization that does not register with Campaign Verify and provide a token during 10DLC registration will be allowed to register with standard use cases, but will receive the lowest tier of A2P messaging limits and will not qualify for the Political Special Use Case. In addition, you may be subject to penalties from carriers if political messaging traffic is incorrectly registered with standard use cases. You must import your Campaign Verify token during the Brand Creation step.

                                                                                                                                            Register with Campaign Verify to submit information about your political organization and verify your identity as an authorized person associated with the organization. You will receive a Campaign Verify token (vetting_id) which you will need for the following API call. ISVs that are sending messages on behalf of 527 organizations must collect Campaign Verify tokens from their customers and provide them during the A2P brand registration steps as described below.

                                                                                                                                            A2P brands with a Campaign Verify token successfully attached will only qualify for the Political special use case — all standard use cases will be disabled for this brand. This is both so that political organizations can take advantage of increased messaging limits associated with the Political campaign use case, and so that all messages from 527s are correctly categorized as political traffic.

                                                                                                                                            What does this do? This create call to the brand_vettings endpoint attaches a Campaign Verify token to an existing A2P Brand to prove its status as a 527 Organization. This will unlock the ability to register with the Political Special Use Case and receive increased A2P messaging limits from carriers. You will need to pass your vetting_id in the body of this request to associate it with your A2P Brand and assert your brand status as a verified 527 Political Organization within the carrier ecosystem.

                                                                                                                                            Parameter

                                                                                                                                            Details

                                                                                                                                            brand_sid

                                                                                                                                            The SID of the A2P Brand for which you are importing a Campaign Verify ID. This Brand must have been created with the "Nonprofit" company type to import a Campaign Verify token.

                                                                                                                                            vetting_provider

                                                                                                                                            The third-party provider that has conducted the vetting. Set to "campaign-verify" for Campaign Verify tokens.

                                                                                                                                            vetting_id

                                                                                                                                            The unique identifier of the vetting from the third-party provider. Set this to your Campaign Verify token string.

                                                                                                                                            Loading Code Sample...
                                                                                                                                                  
                                                                                                                                                  

                                                                                                                                                  Import Campaign verify ID on an existing brand (527 Political Organizations)

                                                                                                                                                  3.3 Fetch all external vetting records (527 Political Organizations)

                                                                                                                                                  What does this do? This call (list or read, depending on the library) to the brand_vettings endpoint fetches a list of all vetting records attached to a brand_sid. Each object inside of the response array contains a vetting_sidand its associated vetting_id. Returns all external vetting records applied to the brand for Campaign Verify.

                                                                                                                                                  Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status parameter.

                                                                                                                                                  The statuses for external vetting records are:

                                                                                                                                                  • IN_PROGRESS: The attempt to import the vetting record is in progress.
                                                                                                                                                  • SUCCESS: The vetting record has been successfully applied to the brand.
                                                                                                                                                  • FAILED: The attempt to apply a vetting record to the brand failed.

                                                                                                                                                  Parameter

                                                                                                                                                  Details

                                                                                                                                                  brand_sid

                                                                                                                                                  The SID of the A2P Brand for which you are fetching vettings.

                                                                                                                                                  vetting_provider

                                                                                                                                                  Set to "campaign-verify" to limit the vetting results to only Campaign Verify token.

                                                                                                                                                  For 527 Political Organizations, ensure that the status of the vetting record is SUCCESS to confirm that the Campaign Verify token has been successfully applied to the brand before moving on to campaign registration. This will unlock the Political special use case and apply increased messaging limits from carriers.

                                                                                                                                                  Loading Code Sample...
                                                                                                                                                        
                                                                                                                                                        

                                                                                                                                                        Fetch all external vetting records (527 Political Organizations)

                                                                                                                                                        3.4 Fetch a single external vetting record (527 Political Organizations)

                                                                                                                                                        What does this do? This call to the brand_vettings endpoint fetches an individual vetting record using a vetting_sid. This call is very much like the previous one (step 3.3 above) except that, since a single vetting_sid is associated with only a single vetting record, just that specified record will be returned. A possible use of this call would be to determine, for example, if the status of a particular vetting record returned in 3.3 had changed, e.g. from IN_PROGRESS to SUCCESS.

                                                                                                                                                        Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status parameter.

                                                                                                                                                        The statuses for external vetting records are:

                                                                                                                                                        • IN_PROGRESS: The attempt to import the vetting record is in progress.
                                                                                                                                                        • SUCCESS: The vetting record has been successfully applied to the brand.
                                                                                                                                                        • FAILED: The attempt to apply a vetting record to the brand failed.

                                                                                                                                                        Parameter

                                                                                                                                                        Details

                                                                                                                                                        brand_sid

                                                                                                                                                        The SID of the A2P Brand for which you are fetching vettings.

                                                                                                                                                        vetting_sid

                                                                                                                                                        The Twilio SID of the third-party vetting record.

                                                                                                                                                        Loading Code Sample...
                                                                                                                                                              
                                                                                                                                                              

                                                                                                                                                              Fetch a single external vetting record (527 Political Organizations)

                                                                                                                                                              4. Create or Choose a Messaging Service

                                                                                                                                                              What does this do? Creates a new Twilio Messaging Service for A2P Messaging, or designates an existing Messaging Service to use in the new Campaign.

                                                                                                                                                              Which API? The Messaging API

                                                                                                                                                              At the beginning of this document, we said that the three main steps involved in new Standard and LVS Brand registration were:

                                                                                                                                                              • Trust Hub registration
                                                                                                                                                              • Brand registration
                                                                                                                                                              • Campaign use case creation

                                                                                                                                                              You have now accomplished the first two of these major steps (Trust Hub registration itself had two parts: the new Standard Customer Profile and the new Trust Bundle). Here you are moving on to the final step, but it too has several pieces. Before you define the actual Campaign use case and other features, in step 5 below, you will first need to either create a new A2P Messaging Service that you will then associate with that new Campaign, or select an existing Messaging Service that you will designate for reuse in the new Campaign (either option will provide the Messaging Service SID that you will use in step 5).

                                                                                                                                                              If you are considering reuse of an existing Messaging Service in the new Campaign, be aware that any Messaging Service can only be associated with one Campaign (and Brand) registration at a time. If you attempt to register a new Campaign in step 5 below and designate an existing Messaging Service that is currently associated with a different Campaign, the new Campaign registration step will fail.

                                                                                                                                                              If you need to programmatically delete an existing Campaign associated with a given Messaging Service, in order to free up that MS for reuse in a new Campaign, step 5.4 below indicates how to do this.

                                                                                                                                                              4.1 Create a new Messaging Service

                                                                                                                                                              New Messaging Services are created via a create call to the services endpoint of the Messaging API. This call, with all of its possible parameters, is detailed in the Messaging API documentation. Please consult this document before creating a new Messaging Service via the API.

                                                                                                                                                              Note that this call has only one required parameter, friendly_name, but there are many optional parameters. The code snippet below specifies two of these optional parameters in addition to friendly_name: inbound_request_url and fallback_url. To configure your Messaging Service to ensure you receive inbound messages, you would need to configure a webhook url using the inbound_request_url parameter. You may also want to configure a fallback webhook url (fallback_url) in case the primary handler fails.

                                                                                                                                                              The sid attribute in the json return from this call will be the messaging_services_sid to be used in section 5 below.

                                                                                                                                                              Loading Code Sample...
                                                                                                                                                                    
                                                                                                                                                                    

                                                                                                                                                                    Create a new Messaging Service

                                                                                                                                                                    4.2 Fetch a Pre-existing Messaging Service

                                                                                                                                                                    As noted above, rather than create a new Messaging Service for this new Brand and Campaign, you may use a pre-existing Messaging Service if you have one that is currently not associated with a campaign, and is appropriate to use for this new one. The API call below is a fetch call to the services endpoint, using the SID of your existing Messaging Service. This call would be useful to inspect all of the attributes currently associated with a given Messaging Service.

                                                                                                                                                                    Loading Code Sample...
                                                                                                                                                                          
                                                                                                                                                                          

                                                                                                                                                                          Fetch Existing Messaging Service

                                                                                                                                                                          5. Create an A2P Campaign

                                                                                                                                                                          What does this do? Creates a required campaign for sending A2P messages around a given use case

                                                                                                                                                                          Which API? The Messaging API

                                                                                                                                                                          5.1 Fetch possible A2P campaign use cases

                                                                                                                                                                          Before you can create your new Campaign, you will need to determine which use case you'd like to specify for it (for a list of all campaign use case types, please see our support article on use case types for A2P 10LC registration). Only one use case can be specified per Campaign. The type of use case that you select greatly impacts the pricing and throughput available to you. Moreover, only a certain subset of all possible use cases are valid for any particular Brand type (e.g. for-profit corporation, non-profit organization, government agency). Thus, the purpose of the API call in this step is to determine what this valid subset is for your brand type, and in this set of valid use cases be able to see which of them, for example, require a post-approval step by your carrier.

                                                                                                                                                                          NOTE: If OTP (One-Time Password) or any other form of 2-Factor Authentication is your only use case for SMS messaging with 10DLC numbers in the U.S., you should investigate Twilio's Verify service to see if this is a better option. With Verify you do not need to worry about A2P registration or any other aspect of sender provisioning.

                                                                                                                                                                          As the code sample below indicates, this will be a fetch call to the us_app_to_person_usecases endpoint of the Messaging API. In this call you will specify the messaging_service_sid, which is the SID of the Messaging Service you either created or selected for reuse in step 4 above (this SID will begin with "MG"). You will also specify the brand_registration_sid, which is the SID returned when you created your new Brand in step 3 (this SID begins with "BN").

                                                                                                                                                                          As an ISV, you will be able to see which Campaign use cases require post-approval using the API call in this step. If the new parameter post_approval_required is set to true, the use case requires an additional carrier review.

                                                                                                                                                                          If you’re a 501(c)(3), we recommend you register using the Charity/501(c)(3) Nonprofit special use case. For more information, please see Registering Campaign Use Cases for Nonprofits.

                                                                                                                                                                          If you have registered a Low-Volume Standard Brand in the steps above, it is recommended that you use Low-Volume Mixed use case for registering your Campaigns

                                                                                                                                                                          Loading Code Sample...
                                                                                                                                                                                
                                                                                                                                                                                

                                                                                                                                                                                Fetch possible A2P campaign use cases

                                                                                                                                                                                5.2 Create A2P Campaign

                                                                                                                                                                                When you create a Campaign, beyond specifying the use case and the Messaging Service to use, you will need to indicate how end users opt-in and give consent to receive messages from this Campaign; you will also need to provide details about how end users can opt-out and receive help, and provide some additional information. For the full set of parameters see the table below.

                                                                                                                                                                                Top reasons for Campaign rejection, and how to avoid them:

                                                                                                                                                                                • missing or unclear message flow (Call to Action) information: the Message Flow describes the process by which end users opt-in to receiving your Campaign's SMS messages. This process must be clearly described and verifiable. If users opt-in through a business website, either provide a direct url to the opt-in form or, if this is not publicly accessible, provide a url to a hosted screenshot of the relevant page (as well as pages showing privacy policies and other information specified below). The url must clearly align with the Brand name provided in the Business Profile in Step 1 above. If Opt-in is done via a paper form, provide a url to a hosted image of this form. If Opt-in is done verbally, provide a script for the solicitation of this opt-in.
                                                                                                                                                                                • TCR cannot verify business website: in the Business Profile creation step, you are asked to provide a public url to the website of the Brand being registered. This url must be functional, it must match in some obvious way the Business Name provided, and the url provided in Step 5.2 below for opt-in (if applicable) and any links included in sample messages. If you are an ISV registering secondary customers, the website provided in this registration must be that of the secondary customer's brand, NOT the ISV as.a business entity.
                                                                                                                                                                                • misalignment between Campaign description, use case, Message flow, sample messages, and/or Brand name: it must be clear and obvious why a particular set of sample messages serves the purposes of a particular Campaign, and why that Campaign serves the purposes of the Brand for which it is registered.

                                                                                                                                                                                Please see A2P 10DLC Campaign Approval Best Practices to ensure your Campaigns meet all requirements.

                                                                                                                                                                                If your A2P Brand registration has failed or is not yet approved, you will receive an error when making this API call. Please ensure that your brand registration status is APPROVED before continuing with this step.

                                                                                                                                                                                Most Twilio customers use Twilio's default or advanced opt-out features. If you use default or advanced opt-out, Twilio will automatically complete your Campaign's opt-out and help parameters with Twilio's default values or your customized advanced opt-out and help values.

                                                                                                                                                                                Creating a Campaign involves a create call to the us_app_to_person endpoint of the Messaging API. There are a total of eight required parameters for this call, and six optional parameters, depending on how much you'd like to explicitly manage opt-in/opt-out mechanisms and help information. Below you will find two different example calls, with the second making more use of these optional parameters.

                                                                                                                                                                                Parameter Description
                                                                                                                                                                                messaging_service_sid The SID (begins with "MG") of the Messaging Service you either created or chose for reuse in step 4.
                                                                                                                                                                                brand_registration_sid The SID of the Brand you created in step 3 above. It will begin with "BN".
                                                                                                                                                                                description

                                                                                                                                                                                This should be a fairly detailed description of what purpose this campaign serves. The description should provide an explanation of who the sender is, who the recipient is, and why messages are being sent to the intended recipient. Min length: 40 characters. Max length: 4096 characters. This description must align with the use_case you specify below. and should be descriptive enough to pass manual reviews.

                                                                                                                                                                                Example: "This Campaign will send weekly marketing messages about sales and offers from Acme Sandwich Company to end customers who have opted in"

                                                                                                                                                                                NOTE: If you are a financial institution engaged in direct, first-party lending to your customers, please indicate "Direct Lending" in the Campaign description so that our review team can properly set this attribute before submitting the registration to TCR. Please indicate this even if your Campaign use case is not directly related to your offer of lending services (e.g. OTP).

                                                                                                                                                                                message_flow

                                                                                                                                                                                Required for all Campaigns. Details around how a consumer opts-in to their campaign, therefore giving consent to receive their messages. If multiple opt-in methods can be used for the same campaign, they must all be listed. 40 character minimum. 2048 character maximum.

                                                                                                                                                                                If a website is used for opting in, provide a link to the website. The website needs to have a privacy policy and terms of service. Privacy policies also need to include a statement of non-sharing for mobile numbers, message frequency, and "message and data rates may apply" disclosure. You need to provide a link to the policy.

                                                                                                                                                                                If this opt-in mechanism and other required information is not publicly accessible at the business website url you have provided, please provide a url with hosted screenshots of the relevant pages. Understanding the opt-in mechanism is critical to the acceptance of the Campaign by TCR.

                                                                                                                                                                                Example: "End users opt-in by visiting www.acmesandwich.com and adding their phone number. They then check a box agreeing to receive text messages from Acme Sandwiches. Additionally, end users can also opt-in by texting START to (111) 222-3333 to opt in. Term and Conditions at www.acmesandwich.com/tc. Privacy Policy at www.acmesandwich.com/privacy"

                                                                                                                                                                                message_samples

                                                                                                                                                                                An array of sample message strings, min two and max five. Min length for each sample: 20 chars. Max length for each sample: 1024 chars.

                                                                                                                                                                                Give concrete examples of messages you would send in this Campaign. Sample messages must be clearly aligned with the Campaign description given above and use_case given below. In each message, be sure to identify your Brand by name and/or website. Also, indicate with brackets [] any content that will be conditionalized. Example: "This is a message from the Acme Sandwich Company. Your order for [sandwich type, other item] will be delivered by [time] on [date]. If you have questions or would like to change your order schedule, please call 333-444-1212. If you would like to opt out of future notifications like this, text STOP in reply to this message."

                                                                                                                                                                                us_app_to_person_usecase This must be a valid use case from the list provided to you in step 5.1, e.g. "MARKETING". Make sure your string exactly matches the one from step 5.1, and that it is also aligned with your Campaign description and sample messages above.
                                                                                                                                                                                has_embedded_links Boolean. Indicates that this SMS campaign will send messages that contain url links. Best practice would be to include such links in your sample messages, so that any such links can be verified.
                                                                                                                                                                                has_embedded_phone Boolean. Indicates that this SMS campaign will send messages that contain phone numbers. Again, best practice would be to include any such phone number in your sample messages, so that the number(s) can be verified.
                                                                                                                                                                                opt_in_message (optional) If end users can text in a keyword to start receiving messages from this campaign, the auto-reply messages sent to the end users must be provided here. The opt-in response should include the Brand name, confirmation of opt-in enrollment to a recurring message campaign, how to get help, and clear description of how to opt-out. This field is required IF end users can text in a keyword to start receiving messages from this campaign. 20 character minimum. 320 character maximum
                                                                                                                                                                                opt_out_message (optional) Upon receiving the opt-out keywords from the end users, Twilio customers are expected to send back an auto-generated response, which must provide acknowledgment of the opt-out request and confirmation that no further messages will be sent. It is also recommended that these opt-out messages include the brand name. This field is required IF you are managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum (this field is required if you are managing the opt-outs by yourself).
                                                                                                                                                                                help_message (optional) When customers receive the help keywords from their end users, Twilio customers are expected to send back an auto-generated response; this may include the brand name and additional support contact information. This field is required IF you are managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum (this field is required if you are managing the opt-outs by yourself).
                                                                                                                                                                                opt_in_keywords (optional) If end users can text in a keyword to start receiving messages from this campaign, those keywords must be provided, in a comma-delimited list if more than one. This field is required if end users can text in a keyword to start receiving messages from this campaign. 255 character maximum.
                                                                                                                                                                                opt_out_keywords (optional) End users should be able to text in a keyword to stop receiving messages from this campaign. Those keywords must be provided here, if you are managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum (this field is required if you are managing the opt-outs by yourself).
                                                                                                                                                                                help_keywords (optional) End users should be able to text in a keyword to receive help. Those keywords must be provided as part of the campaign registration request, IF you are managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum (this field is required if you are managing the opt-outs by yourself).

                                                                                                                                                                                Please note that the path used in this Campaign creation call is the Messaging Service SID, e.g. in Python, client.messaging.v1.services('MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'), prior to any of the actual input parameters. This is a reminder that Campaigns are built around a pre-existing Messaging Service, which is why you either created one or selected a pre-existing one in Step 4 above. Campaigns cannot be created except in association with a Messaging Service.

                                                                                                                                                                                By the same token, once a Campaign has been created, deleting its associated Messaging Service (either via API call or via the Console) will necessarily mean deleting the Campaign itself. This would be especially undesirable, in most cases, once a Campaign has been VERIFIED (approved), as the Campaign approval process would need to be re-initiated from scratch.

                                                                                                                                                                                Note finally that the Campaign itself can be deleted, if necessary, without deleting the Messaging Service; this is addressed in Section 5.4 below.

                                                                                                                                                                                You can can create up to five Campaigns per Brand, unless a clear and valid business reason is provided for exceeding this limit.

                                                                                                                                                                                The first code example below demonstrates how you could create a campaign if you are using Twilio's default or advanced opt-out. The opt-out and help parameters are not required, because Twilio will automatically complete those.

                                                                                                                                                                                Twilio customers who do not use default or advanced opt-out will need to provide opt-out and help keywords and messages.

                                                                                                                                                                                Loading Code Sample...
                                                                                                                                                                                      
                                                                                                                                                                                      

                                                                                                                                                                                      Create A2P Messaging campaign use case for default and advanced opt-out users

                                                                                                                                                                                      Customers managing their own opt-out will need to provide additional opt-out and help information when registering a Campaign, as demonstrated in this second sample call.

                                                                                                                                                                                      Loading Code Sample...
                                                                                                                                                                                            
                                                                                                                                                                                            

                                                                                                                                                                                            Create A2P Messaging campaign use case for customers managing their own opt-out

                                                                                                                                                                                            5.3 Check your Campaign registration status

                                                                                                                                                                                            NOTE: it is now possible to set up and subscribe to Campaign status Event Streams, so that an event message will be sent to a specified webhook url when the new Campaign has been approved or has been rejected. Please see this guide for setting up the necessary Event Streams sinks and event subscriptions, and for information on reading each event message payload. In the event of a Campaign rejection, you will then need to perform the fetch call described below in order to learn details about the failure reason(s).

                                                                                                                                                                                            Just as you did when you submitted your new Brand for review in Step 3, after you've submitted your new Campaign you can check on the status of its approval process using a fetch call to the same us_app_to_person endpoint that you used to create the Campaign. This will be particularly useful for a Campaign with a use case that requires post-approval (i.e., an additional approval step by your mobile carrier).

                                                                                                                                                                                            This fetch call requires two parameters: the messaging_service_sid (i.e., the SID of the Messaging Service you're using in this Campaign), and a hardcoded compliance type of QE2c6890da8086d771620e9b13fadeba0b (see code sample below for how these are used in your code library of choice).

                                                                                                                                                                                            In this call's json response, the attribute campaign_id is a seven-character string that will have been added to the new Campaign record by the Campaign Registry (TCR). But in this response, you would be looking in particular at the campaign_status attribute. The possible statuses for campaigns will vary depending on what stage the Campaign is at in the review process. A newly-created Campaign that has yet to be considered by TCR will be PENDING, assuming that the Twilio API itself has accepted it (i.e., all the data is basically conforming); otherwise it will be FAILED. Once TCR has begun its own review process on a successfully-submitted Campaign, the Campaign will be IN_PROGRESS until that review has finished. At that point the campaign_status will be either VERIFIED (approved) or FAILED (rejected). In certain rare case the status may instead be SUSPENDED; if your Campaign has a Suspended status please see our A2P Campaign Troubleshooting Guide.

                                                                                                                                                                                            If campaign_status is FAILED, the response will contain an “errors” attribute with the information on why the registration failed (but please note that this is only the case for Campaigns submitted since May 31, when this feature was implemented; for previous Campaigns the errors[] attribute will be empty). The populated errors[] attribute is particularly helpful if the campaign registration failed during Twilio’s internal review or External campaign review by our partners.

                                                                                                                                                                                            If your Campaign is marked as FAILED, please see our Campaign Troubleshooting Guide to understand Campaign error messages and how to rectify these

                                                                                                                                                                                            Loading Code Sample...
                                                                                                                                                                                                  
                                                                                                                                                                                                  

                                                                                                                                                                                                  GET A2P Messaging Campaign

                                                                                                                                                                                                  5.4 DELETE an A2P Campaign (Optional)

                                                                                                                                                                                                  If you need to unregister or delete a campaign, you can make the following delete request to the Messaging Service us_app_to_person endpoint. Again, here you will specify the compliance type QE2c6890da8086d771620e9b13fadeba0b in your request.

                                                                                                                                                                                                  After your API request is accepted, please allow a few seconds for deletion to be finalized in our system.

                                                                                                                                                                                                  As noted in section 4 above, one of the reasons you might want to delete an existing Campaign would be to reuse the Messaging Service associated with that Campaign for a new Campaign. If you are doing this programmatically, we recommend implementing a 5-second delay between removing the existing Campaign and creating a new one using the same Messaging Service, so that your Campaign creation does not fail.

                                                                                                                                                                                                  Loading Code Sample...
                                                                                                                                                                                                        
                                                                                                                                                                                                        

                                                                                                                                                                                                        (Optional) DELETE A2P Messaging campaign use case

                                                                                                                                                                                                        6. Ensure that a Twilio 10DLC phone number is associated with your new Campaign

                                                                                                                                                                                                        Once your Business Profile, Brand, and Campaign have been registered and verified, the final step before you can begin using the new Messaging Campaign is to ensure that the Twilio 10DLC phone number or numbers you use to send messages to the US are associated with the new Campaign’s Messaging Service as the Sender. To do this via the API:

                                                                                                                                                                                                        1. See this part of the PhoneNumber Resource guide for the API call to associate a given phone number (by phone_number_sid) with the new Messaging Service (by messaging_service_sid) you’ve created for the new A2P Campaign.
                                                                                                                                                                                                        2. You can subsequently use a GET call on that same phone_numbers endpoint as in (2) above to confirm that the phone number is associated with this Messaging Service (see this part of the same PhoneNumberResource guide).

                                                                                                                                                                                                        If you do not currently have any Twilio 10DLC phone numbers you’d like to use with the new Messaging Service, you can select and buy one either via the Twilio Console or via API – see this guide for details on both.

                                                                                                                                                                                                        NOTE: Whether or not you choose to reuse existing Twilio phone numbers in the context of this particular Campaign registration, please be aware that any Twilio 10DLC numbers you currently have, and that you wish to continue using for SMS messaging within the U.S., must be registered as senders for A2P Messaging Services (ie officially associated with some officially registered A2P Campaign) as of the Summer of 2023.

                                                                                                                                                                                                        Congratulations! 🎉 You now have a registered Standard or Low-Volume Standard Campaign!

                                                                                                                                                                                                        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