ISV US A2P 10DLC Standard and Low-Volume Standard Registration: API Walkthrough
Please rate limit all API requests for Brand and Campaign registration to 1 request per second.
The process for registering for a Low Volume Standard Brand is the same as registering for a regular Standard Brand, with the only exception that Low Volume Standard Brands must skip secondary vetting when creating an A2P Brand (skip_automatic_sec_vet
should be True when you create an A2P Brand). For more on Standard vs Low-Volume Standard see Section 3 below.
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. You will be registering your end users' brands as either Standard Brands or Low-Volume Standard Brands (see Section 3 below for the difference between the two).
You will be working with three different APIs to cover the main steps of this registration 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.
Additionally, be sure you're using the latest version of the Twilio Helper Libraries to perform the API calls in this walkthrough.
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.
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
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 of this profile should represent your customer. The Email address you provide in this step will receive an email notification when this Secondary Customer Profile changes status to approved or rejected (following Brand registration), so the email address provided can either be yours or your client's.
Secondary Customer Profiles can live at either the parent or subaccount levels. If you are creating these within a subaccount, the AccountSID that you use in the following requests should be that of the Subaccount.
In this step, there is an optional parameter:
Parameter | Details |
status_callback |
|
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.
Updates are coming to Twilio’s Starter Brand registration based on changes from The Campaign Registry (TCR) and mobile carriers. We will provide updates on how this change may impact US A2P 10DLC registration as soon as they are available. Brands with EINs will no longer be able to use Twilio's Starter Brand registration going forward.
In the meantime, if you are registering on behalf of an organization with an EIN/Tax ID, please complete a Standard registration.
The email
value you provide should be your ISV’s notification email address that can receive emails about the status of the secondary customer profile, such as Twilio approving or rejecting the profile and TCR approving or rejecting the Brand.
Note: In this step, there are parameters with multiple valid values:
Parameter | Valid values |
business_type |
|
business_industry |
|
business_registration_identifier |
|
business_identity |
Note: The |
business_regions_of_operation |
|
1.4 Create end-user of type: authorized_representative_1
This step provides required information about an authorized business representative. This contact information should pertain to the secondary client you are registering, NOT to yourself as an ISV.
In this step, there are parameters with multiple valid values:
Parameter | Valid values |
business_title |
|
job_position |
|
1.5 Create end-user of type: authorized_representative_2 (optional)
This step provides optional information about a second authorized business representative for the secondary customer profile.
1.6 Create supporting document: customer_profile_address
This step creates an object representing your customer’s address information if you don’t already have one for the customer. Alternatively, if you already have an address, skip to the next code block.
Create customer document (when you have a valid AddressSID)
In this step, there are parameters with multiple valid values:
Parameter | Valid values |
region |
|
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.
- authorized_representative_1 and optionally authorized_representative_2
- supporting document (address)
- customer_profile_business_information
- 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.
- As an ISV registering one of your customers, you will need to attach the
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
What does this do? Creates an A2P Profile (a bundle of information) that you will submit with your Customer Profile to the Campaign Registry
Which API? The TrustHub API
These next steps take the secondary customer profile and prepare it for submission to The Campaign Registry (TCR). This is a requirement before a customer can create A2P messaging campaign use cases.
In the following steps, there are parameters with multiple valid values:
Parameter | Valid values |
company_type |
|
|
|
2.1 Fetch A2P Profile Policy
Fetch the policy for A2P Messaging using Regulation SID RNb0d4771c2c98518d916a3d4cd70a8f8b
Request:
curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN --location --request GET 'https://trusthub.twilio.com/v1/Policies/RNb0d4771c2c98518d916a3d4cd70a8f8b'
Response:
{
"friendly_name": "A2P Messaging: Local - Business",
"requirements": {
"end_user": [
{
"fields": [
"company_type",
"stock_exchange",
"stock_ticker"
],
"name": "US A2P brand General Business Information",
"requirement_name": "us_a2p_messaging_profile_information",
"type": "us_a2p_messaging_profile_information",
"url": "/EndUserTypes/us_a2p_messaging_profile_information"
}
],
"supporting_customer_profiles": [
{
"name": "Primary Customer Profile Bundle Proof",
"requirement_name": "primary_customer_profile",
"type": "bundle"
},
{
"name": "Secondary Customer Profile Bundle Proof",
"requirement_name": "secondary_customer_profile",
"type": "bundle"
}
],
"supporting_document": [
[]
],
"supporting_trust_products": []
},
"sid": "RNb0d4771c2c98518d916a3d4cd70a8f8b",
"url": "https://trusthub.twilio.com/v1/Policies/RNb0d4771c2c98518d916a3d4cd70a8f8b"
}
2.2 Create an empty A2P Trust Bundle
2.3.1 Create an end user of type us_a2p_messaging_profile_information (public companies)
2.3.2 Create an end user of type us_a2p_messaging_profile_information (private companies)
2.3.3 Create an end user of type us_a2p_messaging_profile_information (nonprofit)
Creating a brand with the non-profit company type (as shown here) is essential to unlocking campaign special use cases reserved for particular types of nonprofits. For instance, 501(c)(3)s can only unlock the Charity special use case if their brand is created with the non-profit company type here — this triggers TCR to verify the brand's 501(c)(3) status and, upon success, marks them as qualified for this use case.
2.3.4 Create an end user of type us_a2p_messaging_profile_information (government)
Creating a brand with the government company type (as shown here) is essential to unlocking increased messaging throughput reserved for government agencies. Creating a brand with the government company type here triggers TCR to verify the brand's status as a government entity and, upon success, qualifies the brand for increased throughput (T-Mobile: Unlimited daily cap, AT&T: TBD MPS).
2.4 Assign the end user to the A2P Trust Bundle
2.5 Assign secondary customer profile bundle to A2P trust bundle
This step ties your A2P trust bundle back to the secondary customer profile you created earlier.
2.6 Run evaluation on A2P Trust Product
The response’s status
parameter has two valid string values:
compliant
noncompliant
By running an evaluation, you check that all the necessary A2P Bundle information has been added. If there are no errors, you will get a status of compliant
. If there are errors, the evaluation will fail and error codes will be surfaced to you.
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: The first code sample below creates a Standard A2P Brand. The second code sample creates a Low-Volume Standard A2P Brand. The second process is identical to the first except that Secondary Vetting is skipped, by setting the parameter SkipAutomaticSecVet
to true
so that the Brand being submitted for registration will only go through primary vetting 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 (hence the name "Low Volume Standard").
For more details on the approach you should choose, see our support article Secondary Vetting for A2P 10DLC.
Low Volume Standard Brands will by default receive the following throughput and messaging limits:
Brand is a Russell 3000 index company? | T-Mobile daily message limit (SMS segments + MMS) | Message throughput tier – Declared use case | Message throughput tier – Mixed/Marketing use case | Message throughput tier - Low volume mixed use case |
---|---|---|---|---|
Yes | 200,000 | 75 MPS per major US carrier | 75 MPS per major US carrier | 1.25 MPS per major US carrier |
No | 2,000 | 4 MPS per major US carrier | 4 MPS per major US carrier | 1.25 MPS per major US carrier |
If you’ve registered a Low Volume Standard brand, and later wish to go through Secondary Vetting and receive higher throughput and messaging limits, please contact Twilio support. The Campaign Registry (TCR) charges $40 for Secondary Vetting, and this fee will be passed onto you.
For more information, please see our support article on Secondary Vetting for A2P 10DLC.
Note for 527 Political Organizations: ISVs registering 527 Political customers should in all cases pass skip_automatic_sec_vet
as true
when creating an A2P Brand. Secondary vetting is not required as A2P messaging limits are determined by your status as a 527 organization.
The same applies to political organizations with a Campaign Verify token as well; they should disable automated Secondary Vetting. Political organization brands will receive increased throughput when a valid Campaign Verify token is uploaded at the brand registration step. See the step below, Import Campaign verify token to an existing brand, for more information.
Note for Government entities and Non-profits: Brand registrations for non-profit and government entities should not skip automatic secondary vetting with the exception of 527 Political customers as described above. Except for 527s, secondary vetting is required to trigger automatic verification of nonprofit or government entity status by TCR and to successfully apply this status to the brand.
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.
A2P Brand Registration can take up to 12 hours in some cases. If you see your brand stuck in the "In Progress" state for more than 12 hours, please reach out to Twilio support team.
Using GET to check brand registration status
You can use the GET
command to check the status of your brand registration.
In this response, there are parameters with multiple values and/or additional relevant information:
Parameter | Possible values and behavior |
status |
|
tcr_id |
|
brand_score |
|
failure_reason |
|
russell_3000 |
|
tax_exempt_status |
Identifies the tax-exempt 501c status for a non-profit brand. If you are not tax-exempt, your
|
skip_automatic_sec_vet |
|
identity_status |
|
government_entity |
|
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 |
|
STOCK_SYMBOL |
|
GOVERNMENT_ENTITY |
|
NONPROFIT |
|
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 Update an A2P Brand
You may perform a brand update a maximum of 3 times at no additional charge. Once you have reached this limit, reach out to Twilio Support for additional assistance.
What does this do? This step allows you to edit the A2P brand you've created after receiving a FAILED
brand status and the tcr_id
is not null. You will use the brand's SID (starting with BN
) to make this api call.
First, review the error message from the brand_feedback
and feedback_reason
parameters. You can use GET (shown above) to check the feedback on your brand registration. Next, you will perform the necessary updates using the relevant TrustHub API endpoints. For example, you may need to update the associated customer profile or update the information attached to the listed end-user.
Once finished, use this update A2P Brand endpoint to update the brand’s registration.
Alternatively, you may review your brand feedback and update your brand via the TrustHub UI in the Twilio Console.
3.2 Import Campaign verify token to an existing brand (527 Political Organizations)
Prequisites
We highly recommend that you review "Registration for 527 Political Organizations" in the ISV Onboarding guide for an overview of the Campaign Verify registration process and Campaign Verify tokens before completing this step.
Note: A 527 organization that does not register with Campaign Verify and provide a token during 10DLC registration will be allowed to register with standard use cases, but will receive the lowest tier of A2P messaging limits and will not qualify for the Political Special Use Case. In addition, you may be subject to penalties from carriers if political messaging traffic is incorrectly registered with standard use cases. You must import your Campaign Verify token during the Brand Creation step.
Register with Campaign Verify to submit information about your political organization and verify your identity as an authorized person associated with the organization. You will receive a Campaign Verify token (vetting_id
) which you will need for the following API call. ISVs that are sending messages on behalf of 527 organizations must collect Campaign Verify tokens from their customers and provide them during the A2P brand registration steps as described below.
A2P brands with a Campaign Verify token successfully attached will only qualify for the Political special use case — all standard use cases will be disabled for this brand. This is both so political organizations can take advantage of increased messaging limits associated with the Political campaign use case, and all messages from 527s are correctly categorized as political traffic.
What does this do? Attaches a Campaign Verify token to an existing A2P brand to prove status as a 527 Organization. This will unlock the ability to register with the Political Special Use Case and receive increased A2P messaging limits from carriers. You will need to pass your vetting_id
in the body of this request to associate it with your A2P Brand and assert your brand status as a verified 527 Political Organization within the carrier ecosystem.
Parameter |
Details |
|
The SID of the A2P Brand for which you are importing a Campaign Verify ID to. Brand must have been created with the "Nonprofit" company type to import a Campaign Verify token. |
|
The third-party provider that has conducted the vetting. Set to "campaign-verify" for Campaign Verify tokens. |
|
The unique identifier of the vetting from the third-party provider. Set this to your Campaign Verify token string. |
3.3 Fetch all external vetting records (527 Political Organizations)
What does this do? Fetches a list of all vetting records attached to a brand_sid
. Each object inside of the response array contains a vettingSID
and it’s associated vettingID
. Returns all external vetting records applied to the brand for Campaign Verify.
Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status
parameter.
The statuses for external vetting records are:
IN_PROGRESS
: The attempt to import the vetting record is in progress.SUCCESS
: The vetting record has been successfully applied to the brand.FAILED
: The attempt to apply a vetting record to the brand failed.
Parameter |
Details |
|
The SID of the A2P Brand for which you are fetching vettings. |
|
Set to "campaign-verify" to limit the vetting results to only Campaign Verify token. |
For 527 Political Organizations, ensure that the status of the vetting record is SUCCESS
to confirm that the Campaign Verify token has been successfully applied to the brand before moving onto campaign registration. This will unlock the Political special use case and apply increased messaging limits from carriers.
3.4 Fetch a single external vetting record (527 Political Organizations)
What does this do? Fetches an individual vetting record using a vetting_sid
.
Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status
parameter.
The statuses for external vetting records are:
IN_PROGRESS
: The attempt to import the vetting record is in progress.SUCCESS
: The vetting record has been successfully applied to the brand.FAILED
: The attempt to apply a vetting record to the brand failed.
Parameter |
Details |
|
The SID of the A2P Brand for which you are fetching vettings. |
|
The Twilio SID of the third-party vetting record. |
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.
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
When you create a Campaign, you will need to indicate how end users opt-in and give consent to receive messages from this Campaign. You will also need to provide details about how end users can opt-out and receive help.
Please see A2P 10DLC Campaign Approval Best Practices to ensure your Campaigns meet all requirements.
Most Twilio customers use Twilio's default or advanced opt-out features. If you use default or advanced opt-out, Twilio will automatically complete your Campaign's opt-out and help parameters with Twilio's default values or your customized advanced opt-out and help values.
For more information about all of the parameters within the Create Campaign API, see the full API documentation.
You can can only create 50 campaigns per use case (for example: 50 marketing campaigns or 50 political campaigns). To create more than 50 campaigns, you'll need to reach out to Twilio Support with an explanation for why more than 50 campaigns of that type are required. Support will request an exception on your behalf. Campaign limit exceptions are granted per brand, on a case by case basis.
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.
The example below demonstrates how you could create a campaign if you are using Twilio's default or advanced opt-out. The opt-out and help parameters are not required, because Twilio will automatically complete those.
Twilio customers who do not use default or advanced opt-out will need to provide opt-out and help keywords and messages.
Customers managing their own opt-out will need to provide additional opt-out and help information when registering a Campaign.
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.
After your API request is accepted, please allow a few seconds for deletion to be finaized in our system. If you are programmatically deleting a Campaign and then creating a new Campaign on the same Messaging Service, we recommend implementing a 5-second delay between removing the existing Campaign and creating a new one on the same Messaging Service.
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:
- Learn how to add phone numbers to a Messaging Service with the PhoneNumber Resource.
- Check out the Twilio Messaging Services API documentation to learn more about the
Service
resource.
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 Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.