メニュー

Expand
ページを評価:

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.

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

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

        パラメーター 詳細
        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:

              パラメーター 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:

                    パラメーター 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
                    • その他
                          
                          
                          

                          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:

                                パラメーター 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:

                                                              パラメーター Valid values
                                                              company_type
                                                              • "private"
                                                              • "public"
                                                              • "non-profit"
                                                              • "govenment"

                                                              stock_exchange

                                                              • "NASDAQ"
                                                              • "NYSE"

                                                              2.1 Fetch A2P Profile Policy

                                                              Fetch the policy for A2P Messaging using Regulation SID RNb0d4771c2c98518d916a3d4cd70a8f8b

                                                              リクエスト:

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

                                                              レスポンス:

                                                              {
                                                                  "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

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

                                                                                                                    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:

                                                                                                                          パラメーター 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
                                                                                                                          • 該当なし
                                                                                                                          skip_automatic_sec_vet

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

                                                                                                                                      
                                                                                                                                      
                                                                                                                                      

                                                                                                                                      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.

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

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

                                                                                                                                                                          
                                                                                                                                                                          
                                                                                                                                                                          

                                                                                                                                                                          関連トピック

                                                                                                                                                                          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:

                                                                                                                                                                          ページを評価:

                                                                                                                                                                          ヘルプが必要ですか?

                                                                                                                                                                          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.

                                                                                                                                                                                
                                                                                                                                                                                
                                                                                                                                                                                

                                                                                                                                                                                フィードバックくださりありがとうございます!

                                                                                                                                                                                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!

                                                                                                                                                                                ステップ1

                                                                                                                                                                                Get link

                                                                                                                                                                                Get a free personal referral link here

                                                                                                                                                                                ステップ2:

                                                                                                                                                                                Give $10

                                                                                                                                                                                Your user signs up and upgrade using link

                                                                                                                                                                                ステップ3

                                                                                                                                                                                Get $10

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