Menu

Expand
Rate this page:

ISV US A2P 10DLC Standard Registration: API Walkthrough

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.

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.

Note: 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

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

              Co-operative

              Limited Liability Partnership

              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

                    
                    
                    

                    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 customers for registration purposes.

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

                                                              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"

                                                              stock_exchange

                                                              • "NASDAQ"
                                                              • "NYSE"
                                                              stock_ticker
                                                              • Maximum length is 4 letters.

                                                              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
                                                                                                              
                                                                                                              
                                                                                                              

                                                                                                              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

                                                                                                                    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.

                                                                                                                    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.

                                                                                                                          
                                                                                                                          
                                                                                                                          
                                                                                                                          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"
                                                                                                                          • "APPROVED"
                                                                                                                          • "FAILED"
                                                                                                                          tcr_id
                                                                                                                          • Only assigned after a successful "APPROVED" 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
                                                                                                                          • false
                                                                                                                          • true, it'll be true when an ISV used this parameter to skip secondary vetting for a brand
                                                                                                                                
                                                                                                                                
                                                                                                                                

                                                                                                                                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.

                                                                                                                                      
                                                                                                                                      
                                                                                                                                      

                                                                                                                                      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.

                                                                                                                                            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

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                        

                                                                                                                                                        5.3 GET A2P Messaging campaign use case

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

                                                                                                                                                              
                                                                                                                                                              
                                                                                                                                                              

                                                                                                                                                              5.4 (Optional) DELETE A2P Messaging campaign use case

                                                                                                                                                              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.

                                                                                                                                                                    
                                                                                                                                                                    
                                                                                                                                                                    
                                                                                                                                                                    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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                                                                                                                                                          
                                                                                                                                                                          
                                                                                                                                                                          

                                                                                                                                                                          Thank you for your feedback!

                                                                                                                                                                          We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                                                                                                                                                          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