Menu

Expand
Rate this page:

ISV US A2P 10DLC Starter Registration: API Walkthrough

This guide is a step-by-step walk through the various API calls you will make to register your customer as a Starter Brand. This involves three different APIs to cover the main actions:

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

For more information on the Starter Brand tier, which is available to ISVs registering their customers for A2P 10DLC, please see our Starter Brand Overview. In fact, we recommend taking the short time to read the overview before following the steps below.

Prerequisite: create a TrustHub Profile for your company

What does this do? It creates a TrustHub Primary Customer Profile for your ISV business.

Which API does it use? None — this task can only be completed in the Trust Hub UI in the Twilio Console.

Before proceeding with the Starter Brand onboarding process for your customers, you must have a Primary Customer Profile in an APPROVED state. You can do this in the Trust Hub UI.

To maximize Trust Scores, please enter the exact legal name, address, and other details as registered for your legal entity. US-based organizations can enter their EIN into this publicly searchable database to get the registered information.

Tip Save the Primary Customer Profile SID from your Profile Details so it can be used in a later step. It will begin with BU.

Registration steps overview

To register your customer as a Starter Brand, you will need to complete these steps and the relevant substeps:

  1. Create a Starter Customer Profile and attach the required information to that profile.
  2. Create an A2P Starter Profile and attach the required information to that profile.
  3. Create an A2P Brand.
  4. Create a Messaging Service.
  5. Create an A2P SMS Campaign use case.

What you will create:

  1. Starter Customer Profile: During the Starter Brand registration process, you will supply information about your customer including their name, email, phone number, and physical address. Twilio will then create a Starter Customer Profile populated with the customer information you provide.
  2. A2P Brand (Starter): The object that gets registered with The Campaign Registry (TCR). The Starter Brand contains all of the supplied information from the Starter Customer Profile and the A2P Starter Bundle.
  3. Messaging Service: A bundling of multiple Twilio senders (phone numbers) with a common set of features and configuration. For more information on Messaging Services, please see our Messaging Services guide.
  4. A2P SMS Campaign use case: An A2P 10DLC use case for your brand that will show the intent of the messages you send with your Messaging Service.

1. Create Starter Customer Profile(s) and attach required information

What does this do? This step creates Starter Customer Profiles for each of your clients using a Trust Hub policy with the identifier RN806dd6cd175f314e1f96a9727ee271f4. Trust Hub supports many types of compliance collections, but this specific policy is for Starter profiles.

Policy SIDs are static, so please use the exact SID shown above in your requests.

Which API does it use? The Trusthub API.

1.1 Fetch the Starter Customer Profile Policy

Request:

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

Response:

{
  "url": "https://trusthub.stage.twilio.com/v1/Policies/RN806dd6cd175f314e1f96a9727ee271f4",
  "requirements": {
    "end_user": [
      {
        "url": "/EndUserTypes/starter_customer_profile_information",
        "fields": [
          "first_name",
          "last_name",
          "email",
          "phone_number"
        ],
        "type": "starter_customer_profile_information",
        "name": "Information",
        "requirement_name": "starter_customer_profile_information"
      }
    ],
    "supporting_trust_products": [],
    "supporting_document": [
      [
        {
          "description": "Customer Profile Address",
          "type": "document",
          "name": "Customer Profile Address",
          "accepted_documents": [
            {
              "url": "/SupportingDocumentTypes/customer_profile_address",
              "fields": [
                "address_sids"
              ],
              "type": "customer_profile_address",
              "name": "Legal Company Address"
            }
          ],
          "requirement_name": "customer_profile_address"
        }
      ]
    ],
    "supporting_customer_profiles": [
      {
        "type": "primary_customer_profile_type_business",
        "name": "Primary Customer Profile Bundle",
        "requirement_name": "primary_customer_profile"
      }
    ]
  },
  "friendly_name": "Starter Customer Profile of type Business",
  "sid": "RN806dd6cd175f314e1f96a9727ee271f4"
}

1.2 Create an empty Starter Customer Profile Bundle

You should complete this step by supplying your customer’s FriendlyName and Email.

        
        
        

        1.3 Create end-user object of type: starter_customer_profile_information

        For ISVs using subaccounts, the Account SID in this step should be replaced with the SID of the subaccount.

              
              
              

              1.4 Create supporting document: customer_profile_address

              Create an address for the Customer Profile.

                    
                    
                    

                    Once you have a valid address SID from the previous step, you can create a customer document.

                          
                          
                          

                          1.5 Assign end-user, supporting document, and primary customer profile to the empty starter customer profile that you created

                          Attach the SIDs from all the steps above to the Starter Customer Profile.

                          1.5.1 Attach the end-user (from Step 1.3) to the Starter Customer Profile

                                
                                
                                

                                1.5.2 Attach the supporting document (from Step 1.4) to the Starter Customer Profile

                                      
                                      
                                      

                                      1.5.3 Attach the primary_customer_profile to the Starter 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 Starter Customer Profile.

                                            
                                            
                                            

                                            1.6 Evaluate the Starter Customer Profile

                                            What does this do? This step will evaluate the Starter Customer Profile against the Starter Customer Profile Policy RN806dd6cd175f314e1f96a9727ee271f4.

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

                                            • compliant
                                            • noncompliant
                                                  
                                                  
                                                  

                                                  1.7 Submit the Starter Customer Profile for review

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

                                                  • draft
                                                  • pending-review
                                                  • in-review
                                                  • twilio-rejected
                                                  • twilio-approved
                                                        
                                                        
                                                        

                                                        2. Create an A2P Starter Profile and attach required information

                                                        What does this do? This step creates an A2P Starter Profile — a bundle of information — that will be sent to The Campaign Registry.

                                                        Which API does it use? The Trusthub API.

                                                        2.1 Fetch an A2P Starter Profile Policy

                                                        Fetch the policy for A2P Messaging using a Trust Hub policy with the identifier RN670d5d2e282a6130ae063b234b6019c8.

                                                        Request:

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

                                                        Response:

                                                        {
                                                          "url": "https://trusthub.twilio.com/v1/Policies/RN670d5d2e282a6130ae063b234b6019c8",
                                                          "requirements": {
                                                            "end_user": [],
                                                            "supporting_trust_products": [],
                                                            "supporting_document": [
                                                              []
                                                            ],
                                                            "supporting_customer_profiles": [
                                                              {
                                                                "type": "primary_customer_profile_type_business",
                                                                "name": "Primary Customer Profile Bundle Proof",
                                                                "requirement_name": "primary_customer_profile"
                                                              },
                                                              {
                                                                "type": "secondary_customer_profile_type_business",
                                                                "name": "Secondary Customer Profile Bundle Proof",
                                                                "requirement_name": "secondary_customer_profile"
                                                              },
                                                              {
                                                                "type": "starter_customer_profile_type_business",
                                                                "name": "Starter Customer Profile Proof",
                                                                "requirement_name": "starter_customer_profile"
                                                              }
                                                            ]
                                                          },
                                                          "friendly_name": "Starter A2P Messaging: Local - Business",
                                                          "sid": "RN670d5d2e282a6130ae063b234b6019c8"
                                                        }
                                                        

                                                        2.2 Create an empty A2P Starter Trust Bundle

                                                              
                                                              
                                                              

                                                              2.3 Assign the Starter Customer Profile bundle to the A2P Starter trust bundle

                                                                    
                                                                    
                                                                    

                                                                    2.4 Evaluate the A2P Starter Profile Bundle

                                                                    Evaluate the A2P Starter Profile Bundle using the Policy SID RN670d5d2e282a6130ae063b234b6019c8.

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

                                                                    • compliant
                                                                    • noncompliant
                                                                          
                                                                          
                                                                          

                                                                          2.5 Submit the A2P Starter Profile bundle for review

                                                                          Submit the A2P Starter Profile bundle for review using the Policy SID RN670d5d2e282a6130ae063b234b6019c8.

                                                                                
                                                                                
                                                                                

                                                                                3. Create an A2P Brand

                                                                                What does this do? This step submits the combined package of your customers' A2P Messaging profile and Customer Profile with the STARTER BrandType to The Campaign Registry.

                                                                                Which API does it use? The Messaging API.

                                                                                      
                                                                                      
                                                                                      

                                                                                      4. Create a Messaging Service

                                                                                      What does this do? This step sets up a Messaging Service and adds up to five US A2P 10 DLC numbers to it.

                                                                                      Which API does it use? 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.

                                                                                            
                                                                                            
                                                                                            

                                                                                            5. Create an A2P SMS Campaign use case

                                                                                            What does this do? This step creates a Starter Campaign use case for sending A2P messages.

                                                                                            Which API does it use? The Messaging API.

                                                                                            5.1 Create an A2P Messaging Campaign Use Case

                                                                                            Create the Messaging campaign using use case STARTER.

                                                                                            Selecting a Starter use case will automatically register a mixed type use case to allow for maximum flexibility. This behavior is different from registering a Standard Brand, where you must choose specific use cases.

                                                                                                  
                                                                                                  
                                                                                                  

                                                                                                  What’s next?

                                                                                                  Congratulations! 🎉 You’re now ready to start sending messages. Take a look at the guides below for more information on Twilio Messaging Services:

                                                                                                  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