Menu

Expand
Rate this page:

ISV US A2P 10DLC Standard Registration: API Walkthrough

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

This guide is a step-by-step walkthrough of the various API calls you will make to register your end users for A2P 10DLC capabilities using Twilio APIs. This involves three different APIs to cover the main steps of the process:

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

If you haven't already done so, we recommend reading our overview of the API-based onboarding flow for A2P 10DLC registration for ISVs.

Additionally, be sure you're using the latest version of the Twilio Helper Libraries to perform the API calls in this walkthrough.

Prerequisite: Create a TrustHub Profile for your Company (ISV)

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

Which API? This can only be done via the TrustHub 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 TrustHub, located in the Twilio Console. In order to register secondary profiles, the primary customer profile needs to have “ISV” selected.

To maximize your Trust score, please enter exactly the details as registered with the IRS. You could put the EIN in this publicly searchable data (URL) and get the registered information for accuracy.

Tip: Copy the primary_customer_profile SID from your Profile Details to be used in a later step. This will begin with BUXXX....

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

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.

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

Which API? TrustHub API

Once you have an approved primary customer profile, create a secondary customer profile for each of your clients. Depending on your Twilio set-up, you may need to create the SCP at the Twilio subaccount or project level.

For each secondary customer profile that you need to register, you must provide several pieces of information. Please consult the table of required information in our ISV US A2P 10DLC Onboarding documentation.

The following cURL commands will guide you through the necessary steps to create a secondary customer profile.

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.

        
        
        

        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 up your own Primary Customer Profile in the Twilio Console. The FriendlyName and Email address you provide here should be that of your customer’s.

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

        In this step, there is an optional parameter:

        Parameter Details
        status_callback
        • It is optional to provide a status callback URL. If provided, all callbacks with bundle information in this and following steps will be sent to the provided URL.
              
              
              

              1.3 Create end-user object of type: customer_profile_business_information

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

              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.

              Note: In this step, there are parameters with multiple valid values:

              Parameter Valid values
              business_type

              Sole Proprietorship

              Partnership

              Limited Liability Corporation

              Co-operative

              Non-profit Corporation

              Corporation

              business_industry

              AUTOMOTIVE

              AGRICULTURE

              BANKING

              CONSUMER

              EDUCATION

              ENGINEERING

              ENERGY

              OIL_AND_GAS

              FAST_MOVING_CONSUMER_GOODS

              FINANCIAL

              FINTECH

              FOOD_AND_BEVERAGE

              GOVERNMENT

              HEALTHCARE

              HOSPITALITY

              INSURANCE

              LEGAL

              MANUFACTURING

              MEDIA

              ONLINE

              RAW_MATERIALS

              REAL_ESTATE

              RELIGION

              RETAIL

              JEWELRY

              TECHNOLOGY

              TELECOMMUNICATIONS

              TRANSPORTATION

              TRAVEL

              ELECTRONICS

              NOT_FOR_PROFIT

              business_registration_identifier

              'USA: Employer Identification Number = EIN'

              'USA: DUNS Number = DUNS'

              'Canada: Canadian Corporation Number= CCN'

              'Great Britain = Company Number'

              'Australia = Company Number from ASIC = ACN'

              'India = Corporate Identity Number'

              'Estonia = VAT Number'

              Romania = VAT Registration Number'

              'Israel = Registration Number'

              'Other'

                    
                    
                    

                    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 may use one point of contact from your own company as the authorized representative across all of your Standard customers for registration purposes. Please note, this does not apply to Starter registrations, which must include the name and contact information of your client.

                    In this step, there are parameters with multiple valid values:

                    Parameter 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
                          
                          
                          

                          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.

                                
                                
                                

                                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.

                                Create customer document (when you have a valid AddressSID)

                                In this step, there are parameters with multiple valid values:

                                Parameter Valid values
                                region
                                • Any correctly spelled state in the United States (US), for example: "New York" or "Washington"
                                • Any correct two-letter abbreviation for a US state, for example: "NY" or "WA"

                                      
                                      
                                      

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

                                      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.

                                            
                                            
                                            

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

                                            Using the SIDs from all the steps above, you will now attach them all to the secondary customer profile.

                                            1. authorized_representative_1 and optionally authorized_representative_2
                                            2. supporting document (address)
                                            3. customer_profile_business_information
                                            4. primary_customer_profile
                                              • As an ISV registering one of your customers, you will need to attach the primary_customer_profile that you created for your own company to the bundle of information represented by this secondary customer profile.

                                            Repeat the following curl command for items 2-4 above to attach the information to the secondary customer profile:

                                                  
                                                  
                                                  

                                                  1.8 Run evaluation on secondary customer profile

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

                                                        
                                                        
                                                        

                                                        1.9 Submit the secondary customer profile for review

                                                        This will submit the secondary customer profile, including all of the bundled information, to Twilio TrustHub for review. This review can take up to 24 hours. During the A2P Transition Period, you can proceed to the next steps without an approved secondary customer profile.

                                                        The status_callback in the response will be the URL provided in step 1.2 unless you provide a new callback URL here.

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

                                                              
                                                              
                                                              

                                                              2. Create an A2P Trust Product

                                                              Secondary Vetting is now required as a part of brand registration for all ISVs and their customers. Twilio is automating the Secondary Vetting process so that you can benefit from increased throughput and daily messaging limits. For more information on automated Secondary Vetting for ISVs, please see the ISV A2P 10DLC Onboarding Guide.

                                                              Political organizations with a Campaign Verify token are not required to go through Secondary Vetting, and should disable automated Secondary Vetting.

                                                              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 TrustHub API

                                                              These next steps take the secondary customer profile and prepare it for submission to The Campaign Registry (TCR). This is a requirement before a customer can create A2P messaging campaign use cases.

                                                              In the following steps, there are parameters with multiple valid values:

                                                              Parameter Valid values
                                                              company_type
                                                              • "private"
                                                              • "public"
                                                              • "non-profit"
                                                              • "government"

                                                              stock_exchange

                                                              • "NASDAQ"
                                                              • "NYSE"

                                                              2.1 Fetch A2P Profile Policy

                                                              Fetch the policy for A2P Messaging using Regulation SID RNb0d4771c2c98518d916a3d4cd70a8f8b

                                                              Request:

                                                              curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN --location --request GET 'https://trusthub.twilio.com/v1/Policies/RNb0d4771c2c98518d916a3d4cd70a8f8b'
                                                              

                                                              Response:

                                                              {
                                                                  "friendly_name": "A2P Messaging: Local - Business",
                                                                  "requirements": {
                                                                      "end_user": [
                                                                          {
                                                                              "fields": [
                                                                                  "company_type",
                                                                                  "stock_exchange",
                                                                                  "stock_ticker"
                                                                              ],
                                                                              "name": "US A2P brand General Business Information",
                                                                              "requirement_name": "us_a2p_messaging_profile_information",
                                                                              "type": "us_a2p_messaging_profile_information",
                                                                              "url": "/EndUserTypes/us_a2p_messaging_profile_information"
                                                                          }
                                                                      ],
                                                                      "supporting_customer_profiles": [
                                                                          {
                                                                              "name": "Primary Customer Profile Bundle Proof",
                                                                              "requirement_name": "primary_customer_profile",
                                                                              "type": "bundle"
                                                                          },
                                                                          {
                                                                              "name": "Secondary Customer Profile Bundle Proof",
                                                                              "requirement_name": "secondary_customer_profile",
                                                                              "type": "bundle"
                                                                          }
                                                                      ],
                                                                      "supporting_document": [
                                                                          []
                                                                      ],
                                                                      "supporting_trust_products": []
                                                                  },
                                                                  "sid": "RNb0d4771c2c98518d916a3d4cd70a8f8b",
                                                                  "url": "https://trusthub.twilio.com/v1/Policies/RNb0d4771c2c98518d916a3d4cd70a8f8b"
                                                              }

                                                              2.2 Create an empty A2P Trust Bundle

                                                                    
                                                                    
                                                                    

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

                                                                                
                                                                                
                                                                                

                                                                                2.3.3 Create an end user of type us_a2p_messaging_profile_information (nonprofit)

                                                                                Creating a brand with the non-profit company type (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 the 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.

                                                                                      
                                                                                      
                                                                                      

                                                                                      2.3.4 Create an end user of type us_a2p_messaging_profile_information (government)

                                                                                      Creating a brand with the government company type (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).

                                                                                            
                                                                                            
                                                                                            

                                                                                            2.4 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 earlier.

                                                                                                        
                                                                                                        
                                                                                                        

                                                                                                        2.6 Run evaluation on A2P Trust Product

                                                                                                        The response’s status parameter has two valid string values:

                                                                                                        • compliant
                                                                                                        • noncompliant

                                                                                                        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.

                                                                                                              
                                                                                                              
                                                                                                              

                                                                                                              2.7 Submit A2P Trust Bundle for review

                                                                                                              This review step puts the Trust Bundle through our automated system for basic validation.

                                                                                                              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.

                                                                                                                    
                                                                                                                    
                                                                                                                    

                                                                                                                    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 in order to get registered.

                                                                                                                    Which API? The Messaging API

                                                                                                                    Note: To create an A2P brand without Secondary Vetting, see optional Step 3.2.

                                                                                                                    Note for 527 Political Organizations: ISVs registering 527 Political customers (Step 3.2) should 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.

                                                                                                                    Note for Government entities and Non-profits: All brand registrations for non-profit and government entities should not skip automatic secondary vetting (skip_automatic_sec_vet should not be set to false) with the exception of 527 Political customers described above (Step 3.2). 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.

                                                                                                                    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.

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

                                                                                                                          
                                                                                                                          
                                                                                                                          
                                                                                                                          Using GET to check brand registration status

                                                                                                                          You can use the GET command to check the status of your brand registration.

                                                                                                                          In this response, there are parameters with multiple values and/or additional relevant 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, you need to wait. 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.
                                                                                                                          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
                                                                                                                          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
                                                                                                                          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. Once you have received feedback on your brand registration, you can contact Twilio support with the appropriate corrected information to update your brand.

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

                                                                                                                                
                                                                                                                                
                                                                                                                                

                                                                                                                                3.1 Update an A2P Brand

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

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

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

                                                                                                                                Once finished, use this update A2P Brand endpoint to update the brand’s registration.

                                                                                                                                Alternatively, you may review your brand feedback and update your brand via the TrustHub UI in the Twilio Console.

                                                                                                                                      
                                                                                                                                      
                                                                                                                                      

                                                                                                                                      3.2 Create an A2P Brand without Secondary Vetting (Optional)

                                                                                                                                      As an ISV, you can skip secondary vetting for one or more of your Secondary Brands (your clients). If the optional parameter SkipAutomaticSecVet is set to true, the brand being submitted will only go through primary vetting (brand registration) 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.

                                                                                                                                      For more details, see our support article Secondary Vetting for A2P 10DLC.

                                                                                                                                      Political organizations with a Campaign Verify token are not required to go through Secondary Vetting, and 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; Secondary Vetting is unnecessary for these brands. See the step below, Import Campaign verify token to an existing brand, for more information.

                                                                                                                                            
                                                                                                                                            
                                                                                                                                            

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

                                                                                                                                            Prequisites

                                                                                                                                            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 political organizations can take advantage of increased messaging limits associated with the Political campaign use case, and all messages from 527s are correctly categorized as political traffic.

                                                                                                                                            What does this do? Attaches a Campaign Verify token to an existing A2P brand to prove 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 to. 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.

                                                                                                                                                  
                                                                                                                                                  
                                                                                                                                                  

                                                                                                                                                  3.4 Fetch all external vetting records (527 Political Organizations)

                                                                                                                                                  What does this do? Fetches a list of all vetting records attached to a brand_sid. Each object inside of the response array contains a vettingSID and it’s associated vettingID. 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 onto campaign registration. This will unlock the Political special use case and apply increased messaging limits from carriers.

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                        

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

                                                                                                                                                        What does this do? Fetches an individual vetting record using a vetting_sid.

                                                                                                                                                        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.

                                                                                                                                                              
                                                                                                                                                              
                                                                                                                                                              

                                                                                                                                                              4. Create Messaging Service

                                                                                                                                                              What does this do? Creates a Twilio Messaging Service for A2P Messaging

                                                                                                                                                              Which API? The Messaging API

                                                                                                                                                              Handling Inbound Messages

                                                                                                                                                              To configure your Messaging Service to ensure you receive inbound messages, you will need to configure a webhook url using the inbound_request_url parameter. You’ll also want to configure a fallback webhook url in case the primary handler fails, using the fallback_url parameter.

                                                                                                                                                              If you would like your inbound messages webhook URL to be set at the phone number level and not at the Messaging Service level, make sure to set use_inbound_webhook_on_number to true when creating your Messaging Service.

                                                                                                                                                                    
                                                                                                                                                                    
                                                                                                                                                                    

                                                                                                                                                                    4.1 Select Pre-existing Messaging Service (Optional)

                                                                                                                                                                    You may select a pre-existing Messaging Service is you have one. Use the SID of your exisitng Messaging Service to fetch it.

                                                                                                                                                                          
                                                                                                                                                                          
                                                                                                                                                                          

                                                                                                                                                                          5. Create A2P SMS campaign use case

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

                                                                                                                                                                          Which API? The Messaging API

                                                                                                                                                                          5.1 Fetch possible A2P campaign use cases

                                                                                                                                                                          The use cases that are returned in the response of this step are determined by the use cases that your brand is qualified for. The type of use case that you select greatly impacts the pricing and throughput available to you. For a list of all campaign use case types, please see our support article on use case types for A2P 10LC registration.

                                                                                                                                                                          As an ISV, you will be able to see which campaign use cases require post-approval using the Fetch possible A2P campaign use cases endpoint from the ISV API. 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.

                                                                                                                                                                                
                                                                                                                                                                                
                                                                                                                                                                                

                                                                                                                                                                                5.2 Create A2P Messaging campaign use case

                                                                                                                                                                                You can can only create 50 campaigns per use case (for example: 50 marketing campaigns or 50 political campaigns). To create more than 50 campaigns, you'll need to reach out to Twilio Support with an explanation for why more than 50 campaigns of that type are required. Support will request an exception on your behalf. Campaign limit exceptions are granted per brand, on a case by case basis.

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

                                                                                                                                                                                      
                                                                                                                                                                                      
                                                                                                                                                                                      

                                                                                                                                                                                      5.3 GET A2P Messaging campaign use case

                                                                                                                                                                                      Retrieve the US A2P campaign use case using the compliance type QE2c6890da8086d771620e9b13fadeba0b

                                                                                                                                                                                            
                                                                                                                                                                                            
                                                                                                                                                                                            

                                                                                                                                                                                            Monitoring Status of Post Approval Campaign

                                                                                                                                                                                            ISVs can confirm that their campaign post-approval is in review using the campaign_status parameter that is returned when fetching the A2P Messaging Campaign Use Case endpoint from the ISV API.

                                                                                                                                                                                            The statuses for post-approval campaigns are:

                                                                                                                                                                                            • In review : the campaign_status value is IN_PROGRESS
                                                                                                                                                                                            • Approved: the campaign_status value is VERIFIED
                                                                                                                                                                                            • Rejected: the campaign_status value is FAILED

                                                                                                                                                                                            5.4 DELETE A2P Messaging campaign use case (Optional)

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

                                                                                                                                                                                                  
                                                                                                                                                                                                  
                                                                                                                                                                                                  

                                                                                                                                                                                                  What's Next?

                                                                                                                                                                                                  Congratulations! 🎉 You now have a registered A2P campaign! If you already had an existing Messaging Service with phone numbers you are ready to start sending messages. If you created new Messaging Services, you will need to add phone numbers to that Messaging Service:

                                                                                                                                                                                                  • Learn how to add phone numbers to a Messaging Service with the PhoneNumber Resource.
                                                                                                                                                                                                  • Check out the Twilio Messaging Services API documentation to learn more about the Service resource.
                                                                                                                                                                                                  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.

                                                                                                                                                                                                        
                                                                                                                                                                                                        
                                                                                                                                                                                                        

                                                                                                                                                                                                        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!

                                                                                                                                                                                                        Refer us and get $10 in 3 simple steps!

                                                                                                                                                                                                        Step 1

                                                                                                                                                                                                        Get link

                                                                                                                                                                                                        Get a free personal referral link here

                                                                                                                                                                                                        Step 2

                                                                                                                                                                                                        Give $10

                                                                                                                                                                                                        Your user signs up and upgrade using link

                                                                                                                                                                                                        Step 3

                                                                                                                                                                                                        Get $10

                                                                                                                                                                                                        1,250 free SMSes
                                                                                                                                                                                                        OR 1,000 free voice mins
                                                                                                                                                                                                        OR 12,000 chats
                                                                                                                                                                                                        OR more