New Sole Proprietor A2P 10DLC Registration for ISVs: API Walkthrough

This API walkthrough is for ISVs who are registering their customers for new A2P 10DLC Sole Proprietor Brands and Campaigns. If you are an ISV who has existing Legacy Starter Brands for customers and want to convert them to the new Sole Proprietor Brand, see the documentation here. If you are not an ISV but rather a direct customer looking to register your own Sole Proprietor Brand for A2P use, please see this guide which will direct you to register your brand via our Console tool.

When registering your customers for Sole Proprietor Brands, you need to provide the following information for each customer. You must use your customer's information for registration. Do not use your own (i.e., the ISV's) information:

Once you have this information for your customers, you can complete their Sole Proprietor registration via the API. API registration consists of the following steps:

1. Create a Starter Profile (a Starter Profile is used for later creating a Sole Proprietor Brand and Campaign, and can also be used for registering other products within TrustHub)
2. Create a Sole Proprietor A2P Trust Bundle
3. Create a Sole Proprietor Brand and complete OTP verification (you should only register 1 Sole Proprietor Brand for each unique customer)
4. Create a Sole Proprietor Campaign (each Sole Proprietor Brand can only have one Campaign)
5. Add a Phone Number to the Campaign (each Sole Proprietor Campaign can only use one Phone Number to send messages)

Prerequisite: Create a Trust Hub Profile for your Company (ISV)

What does this do? Creates a Trust Hub profile for your business (the ISV).

Which API? This can only be done via the Trust Hub UI in the Twilio Console.

To get the highest possible messaging limits, please create your profile with details that exactly match those in your US EIN listing (or that of your relevant national Tax ID if your ISV business is located outside the U.S.). If there are any differences – for example, in the business name or address – your messaging limits will be lower. Please verify these details via your W2 form or equivalent national tax record.

Tip: Copy the Primary Customer Profile's bundle SID (BUxxx) from Customer Profile Details page to be used in a later step; see https://console.twilio.com/us1/account/trust-hub/customer-profiles > View profile details button

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

Which API? Trust Hub API

This step creates Starter Customer Profiles for 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 can be used for Sole Proprietor Brands.

1.1 Fetch the Starter Customer Profile Policy

The Starter Customer Profile Policy contains all of the fields you need to complete when creating a Starter Customer Profile. You can refer back to this throughout the registration process to ensure you are completing the necessary fields. When you have completed the Starter Customer Profile for this customer, you will submit it to be evaluated against this Customer Profile Policy (in step 1.7 of this walkthrough) to ensure that it meets all requirements.

The SID for the Starter Customer Profile Policy is RN806dd6cd175f314e1f96a9727ee271f4.

1.2 Create a Starter Customer Profile Bundle

This Starter Customer Profile Bundle contains information about your customer. You will fill out some of the fields now, and will attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 1 of this walkthrough.

You will use the SID from this new Customer Profile Bundle you created (the SID begins with BU) in a later step.

1.3 Create an end-user object with the type starter_customer_profile_information

The attributes object should contain the following fields:

{
   "email": "starter-profile-enduser@example.com",
   "first_name": "John",
   "last_name": "Doe",
   "phone_number": "+11234567890"
}

You will use the SID of the new end-user object you created (the SID begins with IT) in a later step.

1.4 Create a supporting document: customer_profile_address

Here, you create an Address object for the customer, which you then attach to their customer profile. Note that you can only use a valid US or Canadian address if you are creating a Sole Proprietor registration.

Provide the following parameters to the API request:

1.5 Create a Supporting Document with the Address from Step 1.4

Once you have a valid address SID from this Address object you just created (the SID beings with AD), you can create a Supporting Document object. This Supporting Document will later be assigned to the Starter Customer Profile Bundle that you created in step 1.2.

The Supporting Document will need the following values:

The attributes object should look like this:

{
   "address_sids": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

You will use the SID from this new Supporting Document (the SID begins with RD) in the next step.

1.6 Assign End-User, Supporting Document, and Primary Customer Profile to the Starter Customer Profile that you created

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.5): Begins with RD
• Primary Customer Profile Bundle SID (from parent account, mentioned in the Prerequisites section): Begins with BU

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

The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the End-User Object SID from step 1.3. See the code sample below as an example.

1.6.2 Attach the Supporting Document (from Step 1.4) to the Starter Customer Profile

The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Supporting Document SID from step 1.5. See the code sample below as an example.

1.6.3 Attach the Primary Customer Profile Bundle to the Starter Customer Profile Bundle

This step is applicable only for ISV customers of Twilio. ISV customers should already have Primary Customer Profile setup in their parent/main account from where they can fetch its Bundle SID (the SID starts with BU). See the Prerequisites for more information.

The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Primary Customer Bundle SID. See the code sample below as an example.

1.7 Evaluate the Starter Customer Profile

This step evaluates the Starter Customer Profile against the Starter Customer Profile Policy (which you fetched in step 1.1; the Starter Customer Profile Policy has the SID RN806dd6cd175f314e1f96a9727ee271f4).

The Starter Customer Profile SID from step 1.2 is the path parameter for this request. The body of the request should contain one parameter, called policy_sid, which is the hardcoded Policy SID RN806dd6cd175f314e1f96a9727ee271f4.

If your Starter Customer Profile is missing any required information, the response to the API request will indicate that those fields are not complete. You should go back and complete the missing fields from the previous steps.

If your Starter Customer Profile matches the expected Starter Customer Profile Policy, the response will indicate that the profile is compliant and that you can move on to the next step.

1.8 Submit the Starter Customer Profile for review

Once you have evaluated the Starter Customer Profile against the Starter Customer Profile Policy and the response says that the profile is compliant, you are ready to submit the profile.

The Starter Customer Profile status field has the following possible values:

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

When you first create the profile, it will be in the draft state. To submit the profile for review, you update the profile's status to pending-review via API request (the example of this request is below). The result of this API request will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough.

2. Create a new Sole Proprietor A2P Trust Bundle and attach required information

Which API? Trust Hub API

Once your Starter Customer Profile from the previous step is in_review, you can create a new Sole Proprietor Trust Bundle for your customer, which you will then use to complete a Sole Proprietor Brand. The steps in this section are very similar to the ones you completed in Section 1, but you will provide different information about your customer here.

2.1 Fetch the Sole Proprietor A2P Trust Policy

Similar to Step 1.1, fetch the Sole Proprietor A2P Trust Policy to help you determine if you are meeting all the requirements for your Trust Bundle before you submit it.

The Sole Proprietor A2P Trust Policy contains all of the fields you need to complete when creating a Sole Proprietor Trust Bundle. You can refer back to this throughout the registration process to ensure you are completing the necessary fields. When you have completed the Sole Proprietor Trust Bundle for this customer, you will submit it to be evaluated against this Trust Policy to ensure that it meets all requirements.

The SID for the Starter Customer Profile Policy is RN670d5d2e282a6130ae063b234b6019c8.

2.2 Create a Sole Proprietor A2P Trust Bundle

This Sole Proprietor A2P Trust Bundle contains information about your customer (from the profile you created above) and their Brand. You fill out some of the fields now, and attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 2 of this walkthrough.

These are the parameters for the API request to create a Sole Proprietor A2P Trust Bundle:

You will use the SID from this new Sole Proprietor Trust Bundle you created (the SID begins with BU) in a later step.

2.3 Create end-user object with the type sole_proprietor_information

In this step, you provide information about your customer's brand name, their mobile number for their Sole Proprietor Brand verification, and optionally their business vertical.

Include the following parameters in your API request:

The attributes object should look like this:

{
   "brand_name": "John Doe",
   "vertical": "COMMUNICATION",
   "mobile_phone_number": "+11234567890"
}

The optional vertical field describes the customer's business. It can be one of the following values:

• AGRICULTURE

• COMMUNICATION

• CONSTRUCTION

• EDUCATION

• ENERGY

• ENTERTAINMENT

• FINANCIAL

• GAMBLING

• GOVERNMENT

• HEALTHCARE

• HOSPITALITY

• HUMAN_RESOURCES

• INSURANCE

• LEGAL

• MANUFACTURING

• NGO

• POLITICAL

• POSTAL

• PROFESSIONAL

• REAL_ESTATE

• RETAIL

• TECHNOLOGY

• TRANSPORTATION

You will use the SID from this new end-user you created (the SID begins with IT) in the next step.

2.4 Assign the end-user and starter customer profile to the Sole Proprietor A2P Trust Bundle

Attach the SIDs from the end-user object you created in step 2.3 and the Starter Customer Profile you created in step 1.2 to the Sole Proprietor Trust Bundle you created in step 2.2 (the SID for the Sole Proprietor Trust Bundle begins with BU).

• End-User Object SID (step 2.3): SID begins with IT.
• Starter Customer Profile SID (step 1.2): SID begins with BU.

2.4.1 Attach the end-user (from Step 2.3) to the Sole Proprietor A2P Bundle

The Sole Proprietor A2P Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the End-User Object SID from step 2.3. See the code sample below as an example.

2.4.2 Assign the Starter Customer Profile Bundle to the Sole Proprietor A2P Trust Bundle

The Sole Proprietor A2P Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called object_sid, which is the Starter Customer Profile Bundle SID from step 1.3. See the code sample below as an example.

2.5 Evaluate the Sole Proprietor A2P Trust Bundle

This step evaluates the Sole Proprietor A2P Trust Bundle against the Sole Proprietor A2P Trust Policy (which you fetched in step 2.1; the Sole Proprietor A2P Trust Policy has the SID RN670d5d2e282a6130ae063b234b6019c8).

The Sole Proprietor Trust Bundle SID from step 2.2 is the path parameter for this request. The body of the request should contain one parameter, called policy_sid, which is the hardcoded Policy SID RN670d5d2e282a6130ae063b234b6019c8.

If your Sole Proprietor Trust Bundle is missing any required information, the response to the API request will indicate that those fields are not complete. You should go back and complete the missing fields from the previous steps.

If your Sole Proprietor Trust Bundle matches the expected Sole Proprietor Trust Policy, the response will indicate that the profile is compliant and that you can move on to the next step.

2.6 Submit the Sole Proprietor A2P Trust Bundle for review

Once you have evaluated the Sole Proprietor Trust Bundle against the Sole Proprietor Trust Policy and the response says that the profile is compliant, you are ready to submit the profile.

The Sole Proprietor Trust Bundle status field has the following possible values:

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

When you first create the Trust Bundle, it will be in the draft state. To submit the Trust Bundle for review, update the Bundle's status to pending-review via API request (the example of this request is below). The result of this API request will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough.

3. Create a new Sole Proprietor A2P Brand

Which API? Messaging API

In this step, you will create a Sole Proprietor A2P Brand using the Customer Profile SID from step 1.2 and the Trust Bundle SID from step 2.2. You should have already submitted both of these objects for review in the previous steps, but you shouldn't wait for them to be approved before continuing.

3.1 GET the Sole Proprietor Brand registration status

You can check the status of your customer's Sole Proprietor Brand registration with a GET request. This should update within a few minutes after submitting the Sole Proprietor Brand API request from the step above.

The API will return the following information about the registration:

When the Sole Proprietor Brand first enters the APPROVED state, the identity_status will still be UNVERIFIED. The change to the APPROVED state triggers a new SMS OTP, which is sent to the mobile number registered with the Brand (from step 2.3). The OTP is valid for 24 hours. If your customer does not complete the OTP verification request after 24 hours, you can use this API to trigger a fresh OTP for verification.

The owner of the mobile number will receive a text message sent from +1(915)-278-2000 with the following text: "Please confirm your registration for US A2P Messaging by replying YES. Msg & data rates may apply."

The owner of the mobile number must reply "YES" back to the OTP message to complete Brand verification. Once they do that, they should receive another confirmation message on their mobile number that says "Thank you. Your registration has been confirmed." The Brand state will remain as APPROVED, and their identity_status will now change to VERIFIED

Note that only the first OTP is sent automatically; if your customer does not complete the OTP verification request within 24 hours, you need to send an API request to trigger a new OTP (see step 3.2 for the API request to retrigger this OTP). Additionally, please make every effort to ensure that your customer completes OTP verification within 30 days of Brand registration. At some point going forward, The Campaign Registry (TCR) may begin to enforce a 30-day limit for this OTP completion, after which the Brand registration would be marked as EXPIRED, and would need to be deleted and resubmitted (this documentation will be updated if and when TCR begins to enforce this).

You will need to wait until the Sole Proprietor Brand is approved and verified before moving on to Step 4.

If your Brand registration has FAILED, or if it is APPROVED but with a lower Trust Score than you feel your Brand merits, please see this Guide to Troubleshooting A2P Brands and Campaigns to understand and rectify specific Brand feedback.

The status of SUSPENDED is rare. This status indicates that your Brand is deemed to have potentially violated one or more rules for Brand registration established by the A2P ecosystem partners. This status will require Twilio Support assistance to address. Please see the relevant section of our Troubleshooting guide for details.

3.2 [Optional] Retry OTP Verification for the submitted mobile number

The change from a Sole Proprietor's Brand to the APPROVED state automatically triggers an SMS OTP, which is sent to the mobile number registered with the Brand. The OTP is valid for 24 hours. If your customer does not accept the OTP request after 24 hours, you can use this API to trigger a fresh OTP for verification.

This endpoint has a rate limit of 10 requests per second per account.

You can use the GET API request from 3.1 to check the OTP verification status.

4. Create a new Messaging Service

Which API? Messaging API

In this step, you create a new Messaging Service for your customer. You can later add 10DLC numbers to this Messaging Service and attach the Service to a registered A2P Campaign.

See the documentation here about how to create a new Messaging Service via the API.

5. Create a new Sole Proprietor A2P SMS Campaign

Which API? Messaging API

In this final step, you will create a new Sole Proprietor A2P SMS Campaign. Here, you describe what type of messages the customer is sending to end-users and how those end-users can opt in and out of these messages.

This Campaign can then be attached to a Messaging Service, and the A2P 10DLC numbers in that Messaging Service will be able to send verified A2P 10DLC traffic.

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.

Top reasons for Campaign rejection, and how to avoid them:

• missing or unclear message flow (Call to Action) information: the Message Flow describes the process by which end users opt-in to receiving your Campaign's SMS messages. This process must be clearly described and verifiable. If users opt-in through a business website, either provide a direct url to the opt-in form or, if this is not publicly accessible, provide a url to a hosted screenshot of the relevant page (as well as pages showing privacy policies and other information specified below). The url must clearly align with the Brand name provided in the Business Profile in Step 1 above. If Opt-in is done via a paper form, provide a url to a hosted image of this form. If Opt-in is done verbally, provide a script for the solicitation of this opt-in.
• TCR cannot verify business website: in the Business Profile creation step, you are asked to provide a public url to the website of the Brand being registered. This url must be functional, it must match in some obvious way the Business Name provided, and the url provided in Step 5 below for opt-in (if applicable) and any links included in sample messages. If you are an ISV registering secondary customers, the website provided in this registration must be that of the secondary customer's brand, NOT the ISV as.a business entity.
• misalignment between Campaign description, Message flow, sample messages and/or Brand name: it must be clear and obvious why a particular set of sample messages serves the purposes of a particular Campaign, and why that Campaign serves the purposes of the Brand for which it is registered.

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.

The API request takes the following parameters:

Customers managing their own opt-out will need to provide additional opt-out and help information when registering a Campaign.

5.1 GET the Status of an A2P Messaging Campaign

You can GET your messaging Campaign associated with a Messaging Service and monitor its approval status with the following API request.

In this call's json response, the attribute campaign_id is a seven-character string that will have been added to the new Campaign record by the Campaign Registry (TCR). But in this response you would be looking in particular at the campaign_status attribute. The possible statuses for campaigns will vary depending on what stage the Campaign is at in the review process. A newly-created Campaign that has yet to be considered by TCR will be PENDING, assuming that the Twilio API itself has accepted it (i.e., all the data is basically conforming); otherwise it will be FAILED. Once TCR has begun its own review process on a successfully-submitted Campaign, the Campaign will be IN_PROGRESS until that review has finished. At that point the campaign_status will be either VERIFIED (approved) or FAILED (rejected). In certain rare cases the status will instead be SUSPENDED.

If campaign_status is FAILED, the response will contain an “errors” attribute with the information on why the registration failed (but please note that this is only the case for Campaigns submitted since May 31, when this feature was implemented; for previous Campaigns the errors[] attribute will be empty). This populated errors[] attribute is particularly helpful if the campaign registration failed during Twilio’s internal review or External campaign review by our partners.

If campaign_status is SUSPENDED, please see this section of our Troubleshooting Guide.

If your Campaign registration has been rejected (FAILED), please see this Guide to Troubleshooting A2P Brands and Campaigns to understand error details and rectification.

5.2 [Optional] DELETE A2P Messaging Campaign

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 finalized. If you are programmatically deleting a Campaign and then creating a new Campaign on the same Messaging Service, you should implement at least a 5-second delay between removing the existing Campaign and creating a new one on the same Messaging Service.

6. Ensure that a Twilio 10DLC phone number is associated with your new Campaign

Once your Sole-Proprietor Business Profile, Brand, and Campaign have been registered and verified, the final step before you can begin using the new Messaging Campaign is to ensure that the Twilio 10DLC phone number you use to send messages to the US is associated with the new Campaign’s Messaging Service as the Sender. Here you’ll need to keep several things in mind:

1. For Sole Proprietor Campaigns, only a single 10DLC phone number can be used in the Messaging Service associated with your new Campaign. If you associate more than one phone number with this Messaging Service (or reuse a Messaging Service with more than one number attached), Twilio will randomly pick from among these to register one for A2P use.
2. See this part of the PhoneNumberResource guide for the API call to associate a given phone number (by phone_number_sid) with the new Messaging Service (by messaging_service_sid) you’ve created for the new Sole Proprietor A2P Campaign.
3. You can subsequently use a GET call on that same phone_numbers endpoint as in (2) above to confirm that the phone number is associated with this Messaging Service (see this part of the same PhoneNumberResource guide).

If you do not currently have a Twilio 10DLC phone number you’d like to use with the new Messaging Service, you can select and buy one either via the Twilio Console or via API – see this guide for details on both.

Congratulations! 🎉 You now have a registered A2P Sole Proprietor Campaign!