Rate this page:

Externally Registered Campaigns API

Note: This is a preview of an endpoint that can be made available to you for the purposes of assigning campaigns that you have registered directly with The Campaign Registry (TCR) to phone numbers you own at Twilio, via the Messaging Service. We are still actively working on these APIs and expect to be making updates to them. This API document should be used to help your team scope the amount of integration work to be done.

For more information on what this means, limitations, and reasons why Twilio does not recommend this path see Can I go directly to The Campaign Registry for US A2P 10DLC registration?

The Externally Registered Campaigns API allows you to jump straight to associating a previously registered campaign use case and associate it with a Twilio Messaging Service, skipping all of the Brand registration steps (since you have already registered your brand with The Campaign Registry).

Understanding A2P 10DLC

It is useful to first understand Twilio’s overall model for A2P 10DLC and how this aligns with common customer architectures. The following diagram shows the relationship between Twilio’s Trust Hub, Twilio’s Messaging Services, and where The Campaign Registrys' (TCR) concepts of Brand and Campaign fit into Twilio’s foundational concepts:


Associating Campaigns with Messaging Services

Below are the general steps that you/Twilio will perform in order to associate your Campaigns with Messaging Services:

  1. You create a Twilio Messaging Service via API/Console
  2. You assign phone numbers to the Messaging Service's Sender Pool via API/Console
  3. You, via TCR APIs, share the campaign with Twilio as the Direct Connect Aggregator (DCA).
  4. Twilio, as the DCA, accepts the shared capaign and obtains campaign metadata regarding rate limits and daily messaging caps.
  5. You assign a CampaignID to the Messaging Service that you created using the new Externally Registered Campaigns API.
  6. Twilio ensures every phone number in the Messaging Service's Sender Pool is associated with the CampaignID attached to the Messaging Service.
  7. Twilio willo bill messages and rate limit them according to the Campaign Class.

Deleting Campaigns

If you want to delete the campaign, you have two options:

  1. Delete the Messaging Service resource: If you delete the Messaging Service resource, Twilio ensures that the associated campaign object is deleted. The phone numbers are disassociated and revert back to being unregistered for A2P capabilities.
  2. Delete only the Campaign: If you want to delete only the Campaign, but leave the Messaging Service intact, you can make a request to the A2P endpoint on the Messaging Service to delete only the associated campaign. Twilio will ensure that the phone numbers are disassociated from the campaign, but stay in the Messaging Service’s Sender Pool

If you add/delete phone numbers to the Messaging service, Twilio will perform the necessary registration/deregistration steps with the carriers and other ecosystem service providers.

API Reference

1. Create a Messaging Service

Please note: Do not specify the "usecase" field in request. Twilio will assign a default "undeclared" usecase for the Messaging Service. All existing Messaging Services will have their "usecase" set to "undeclared". For the Externally Registered Campaigns API the "usecase" field will remain undeclared, no matter what is specified with the TCR.


        2. Associate the pre-registered A2P campaign with the Messaging Service

        This step associates the A2P Campaign, which was already registered with TCR, with the Twilio Messaging Service that you just created. From here, Twilio asynchronously retrieves the Campaign information from TCR and updates the A2P ecosystem with Campaign information for all the 10DLC that are part of the Messaging Service’s Sender Pool.

        Kindly rate limit usage of this API for mapping one campaign to one messaging service to a rate limit of once every 5 seconds. Failures from hitting rate limits will be asynchronous and the campaign will move to a failed status after all retries are exhausted. The path forward will then be deleting and re-initiating the API request. This rate limit is so that we are able to accommodate the additional load when sending API requests to TCR, since we are rate limited to TCR.


              3. Get A2P Campaign

              This shows you how to get the details of a campaign that you have imported using the compliance type QE2c6890da8086d771620e9b13fadeba0b. Once the Campaign status is VERIFIED, Twilio bills messages and rate limits them according to the Campaign Class.


                    4. Delete A2P Campaign


                          Frequently Asked Questions

                          For frequently asked questions on the externally registered campaigns API, please see Can I go directly to The Campaign Registry for US A2P 10DLC registration?

                          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