Menu

Expand
Rate this page:

ISV US A2P 10DLC Starter 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 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 (parent account) 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

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.

Before you begin, please be sure to use the latest version of the Twilio helper libraries. You can find our SDKs here.

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

What does this do? This step creates Starter Customer Profiles for each of your customers 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.

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

Parameter Valid Values
friendly_name

A string value representing your customer's business name.

email

A string value representing your customer's email address.

policy_sid

The static TrustHub policy identifier for Starter profiles. The hard-coded value is RN806dd6cd175f314e1f96a9727ee271f4.

        
        
        

        1.3 Create end-user object with the type: starter_customer_profile_information

        Please note that you cannot reuse contact information per each Starter Brand you create.

        Parameter Valid Values
        attributes

        An object containing your customer's first name, last name, email address, and phone number.

        friendly_name

        A string value representing the end-user object you create in this step.

        type

        The end user object type: starter_customer_profile_information.

              
              
              

              1.4 Create supporting document: customer_profile_address

              Create an address for the Customer Profile.

              Parameter (* = Required) Valid Values
              Customer Name

              String value representing your customer's name.

              Street Address 1 *

              Example: 1234 Your Street Name

              Street Address 2

              Example: Apt B (if applicable)

              City*

              Example: San Francisco

              Region*

              Can be a State or Province. For example, California (US State) and British Columbia (Canadian Province).

              Postal Code*

              Example: 94016

              IsoCountry

              Please see this list of valid IsoCountry codes.

                    
                    
                    

                    Once you have a valid address SID from the previous step (beginning with AD), you can create a customer document. This customer document will later be assigned to the empty Starter customer profile that you created.

                          
                          
                          

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

                          You will now attach the SIDs from all the steps above to the Starter Customer Profile:

                          • End-User Object SID (step 1.3): Begins with IT.
                          • Starter Customer Profile SID (step 1.2): Begins with BU.
                          • Supporting Document SID (step 1.4): Begins with RD.

                          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.

                                      Both the Primary Customer Profile and the Starter Customer Profile SIDs start with BU. Be sure to note the example SIDs below and in the code sample for this step for a reference on where to pass each SID. Remember, these are just examples and you will pass your own unique SIDs for this step.

                                      • Starter Customer Profile SID: BU48886180931dcaa8cbdc2033cf880b7a. Passed in the URL path.
                                      • Primary Customer Profile SID: BU07d54228ef3eee5c6bffca3d2bd567fb. Passed as the ObjectSid.
                                            
                                            
                                            

                                            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

                                                        Once you have finished creating a Starter Customer Profile you are ready to create an A2P Starter Profile. Let's do that!

                                                        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

                                                        In the response of this step, an A2P Starter Trust bundle SID will be returned (starting with BU). Jot this SID down as you will need it in the next step.

                                                        Parameter Valid Values
                                                        friendly_name

                                                        A string value representing your customer's business name.

                                                        email

                                                        A string value representing your customer's email address.

                                                        policy_sid

                                                        The static A2P Messaging TrustHub policy identifier. The hard-coded value is RN670d5d2e282a6130ae063b234b6019c8.

                                                              
                                                              
                                                              

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

                                                              In this step you will use the A2P Starter trust bundle SID from Step 2.2 and the Starter Customer Profile SID from Step 1.2.

                                                              Both the A2P Starter trust bundle and the Starter Customer Profile SIDs start with BU. Be sure to note the example SIDs below and in the code sample for this step for a reference on where to pass each SID. Remember, these are just examples and you will pass your own unique SIDs for this step.

                                                              • A2P Starter Trust Bundle SID: BU70cb4e72a8486190e181b25c1180c348. Passed in the URL path.
                                                              • Starter Customer Profile SID: BU48886180931dcaa8cbdc2033cf880b7a. Passed as the objectSid.

                                                                    
                                                                    
                                                                    

                                                                    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.

                                                                                
                                                                                
                                                                                

                                                                                At this point, you can proceed immediately to the next step, "Create an A2P Brand". It is normal for your A2P Starter Profile to remain in the Pending state until your Brand is approved.

                                                                                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.

                                                                                      
                                                                                      
                                                                                      
                                                                                      3.1 GET the brand registration status

                                                                                      You can make a GET request using curl to check the status of your brand registration. To do so, you will pass your brand SID (starting with BN).

                                                                                      Request:

                                                                                      curl -X GET 'https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
                                                                                      -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

                                                                                      Response:

                                                                                      {
                                                                                         "status":"APPROVED",
                                                                                         "brand_score":42,
                                                                                         "date_updated":"2021-09-15T18:51:40Z",
                                                                                         "customer_profile_bundle_sid":"BUXXXXXXXXXXXXX",
                                                                                         "russell_3000":null,
                                                                                         "account_sid":"ACXXXXXXXXXXXXX",
                                                                                         "brand_type":"STARTER",
                                                                                         "a2p_profile_bundle_sid":"BUXXXXXXXXXXXXX",
                                                                                         "identity_status":"SELF_DECLARED",
                                                                                         "url":"https://messaging.twilio.com/v1/a2p/BrandRegistrations/BNXXXXXXXXXXXXX",
                                                                                         "sid":"BNXXXXXXXXXXXXX",
                                                                                         "tax_exempt_status":null,
                                                                                         "date_created":"2021-09-15T18:51:39Z",
                                                                                         "failure_reason":null,
                                                                                         "skip_automatic_sec_vet":false,
                                                                                         "mock":false,
                                                                                         "tcr_id":"BXXXXXX"
                                                                                      }

                                                                                      Parameter Valid Values
                                                                                      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.

                                                                                      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.

                                                                                      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.

                                                                                            
                                                                                            
                                                                                            

                                                                                            5. Create an A2P SMS Campaign use case

                                                                                            We've made it! We're now finally ready to 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.

                                                                                            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.

                                                                                                  
                                                                                                  
                                                                                                  

                                                                                                  What’s next?

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

                                                                                                  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