Existing Sole Proprietor US A2P 10DLC Registration for ISVs: API Walkthrough
This API walkthrough is for ISVs who have customers with existing legacy Starter Brands created before October 2022, and are updating those Brands for their customers to meet the new Sole Proprietor A2P 10DLC Brand requirements.
Sole Proprietor Brands and Campaigns are only intended for customers in the US and Canada who do not have a tax ID. If your customers have a Tax ID, you must register them for a Standard or Low-Volume Standard Brand. If your customers are located outside of the US or Canada, you must register them for a Standard or Low-Volume Standard Brand to enable them to send messages to the US using 10DLC numbers.
Previously, you may have set up Starter Profiles and A2P Starter Trust Bundles to create the legacy Starter Brands. Here's what you should know to convert the legacy Starter Brand to a new Sole Proprietor Brand.
The Starter Profile should remain in the state twilio-approved
, and require no change from you.
The legacy A2P Starter Trust Bundles have been converted to the new Sole Proprietor A2P Trust Bundles with the same SIDs. The new Sole Proprietor A2P Trust Bundles are incomplete, as they require more information (see table below) than the previous A2P Starter Trust Bundles. The status of these Trust Bundles should be twilio-rejected
.
The legacy Starter Brands have been converted to a new Sole Proprietor Brand with the same SIDs. Once you have updated the Sole Proprietor A2P Trust Bundles, you need to update that information to the Brand, and complete an OTP verification process.
The new requirements for Sole Proprietor A2P Trust Bundles and Brands add the following necessary fields:
Field | Description |
Mobile number |
This mobile number is critical in the registration process and is used for sending a One Time Password (OTP) verification request to the customer, which they must respond to. This must be a valid US or Canadian mobile number only where the customer can be reached. This cannot be a number which you've acquired from a CPaaS provider such as Twilio. This mobile number can only be used a maximum of three times across all A2P Brand registrations with TCR. If your customer is registered for A2P 10DLC with another vendor, that counts towards this limit. |
Brand name |
If your customer is a Sole Proprietor business, this must be the customer's real business name. For Sole Proprietor businesses, their business name is usually their first name and last name, but you can also provide a DBA name if there is one. If your customer is not a business entity but instead is a hobbyist / college student, etc., please provide their first name and last name. This field cannot be a unique identifier such as an account ID or email address. |
Vertical (optional field) |
You can select from a set of predefined values, which are the same as the vertical field in Standard profiles. See the list of available values here. |
This walkthrough assumes that the customer's existing Sole Proprietor A2P Trust Bundle connected to legacy Starter Customer Profile Bundle is in twilio-rejected
state. By April 17th, all Sole Proprietor A2P Trust Bundles that had a legacy Starter Brand attached to it should have been converted to the twilio-rejected
state. If this is not the case, reach out to Support about how to reject the Bundle. This is required for starting this process.
The following steps are required to complete your customer's sole Proprietor Trust Bundle and convert your legacy Starter Brand to a new Sole Proprietor Brand that is compliant with the latest industry requirements for your customer:
- Update the existing Sole Proprietor A2P Trust Bundle with new required information (Brand Name, Mobile Number, and optional Vertical)
- Update the existing Sole Proprietor A2P Brand (and complete OTP verification)
- (Optional) Create a new Sole Proprietor Campaign use case if you do not have one already
1. Update existing Sole Proprietor A2P Trust Bundle with required information
1.1 Fetch Existing Sole Proprietor A2P Bundle
First, fetch the Sole Proprietor A2P Bundle for your customer. This will have the same SID as the legacy Starter Customer Profile you had previously created for this customer.
The status for this Bundle should be twilio-rejected
.
1.2 Fetch entity assignments for the Sole Proprietor A2P Trust Bundle
1.3 Create a new 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.
In this step, you provide your customer's mobile number, which TCR will use to send a One Time Password (OTP) verification request. This must be a valid US or Canadian mobile number where the customer can be reached. This cannot be a number you've acquired from a CPaaS provider such as Twilio.
The customer will receive the OTP message when you submit the Brand for review in step 2. They must respond to the request within 24 hours, or else you will need to retrigger the OTP message using the optional step 2.4.
This mobile number can only be used a maximum of three times for Sole Proprietor A2P Brands. This includes if the customer has registered for a Sole Proprietor Brand with another vendor and has used the same mobile phone number. This limit is managed through TCR and not through Twilio.
Include the following parameters in your API request:
Parameter | Valid Values |
attributes | An object containing your customer's business name (or their first and last name, if they do not have a business name), their mobile phone number, and optionally, their business vertical. Please see the note above about the importance of the customer's mobile phone number for verification. |
friendly_name | A string to identify this end user object for your customer |
type | The string sole_proprietor_information |
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 of the new end-user object you created (the SID begins with IT
) in the next step.
1.4 Attach the end-user (from Step 1.3) to the Sole Proprietor A2P Bundle
The Sole Proprietor A2P Bundle SID from step 1.1 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.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 has the SID RN670d5d2e282a6130ae063b234b6019c8
). The Sole Proprietor A2P Trust Policy contains the required fields for the Trust Bundle. This step informs you if you have any missing or incorrect fields.
The Sole Proprietor Trust Policy SID 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.
1.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
The existing Trust Bundle should be in the twilio-rejected
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.
You should proceed to the next step as soon as the Sole Proprietor A2P Trust Bundle is in the in-review
state. Do not wait for it to be twilio-approved
. The Sole Proprietor A2P Trust Bundle will only reach the twilio-approved
status when a Brand is successfully created and OTP-verified, and you should never wait for this status change.
2. Update existing Sole Proprietor A2P Brand
2.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. The API request will return the following information about the registration. The SID for this Brand is the same as the legacy Starter Brand you created for your customer.
Property | Possible Values |
status | PENDING , APPROVED or FAILED |
identity_status |
The existing Brand will start in
The status changes to |
failure_reason |
Only present if the
|
2.2 Submit Brand update request
This request will use the new information provided in Section 1 to update your brand with The Campaign Registry (TCR). The Sole Proprietor Brand SID is the path parameter for this request.
Once this data is successfully submitted, this will automatically trigger TCR to send an OTP message to the mobile phone number.
2.3 Fetch the latest Sole Proprietor brand registration status
You can check the registration status of the Brand using the same API request from step 2.1.
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 1.3). The OTP is valid for 24 hours. If your customer does not accept the OTP request after 24 hours, you can use the API in Step 2.4 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 2.4 for the API request to retrigger this OTP).
You will need to wait until the Sole Proprietor Brand is in the APPROVED
and VERIFIED
state before moving on to Step 4.
Timely OTP confirmation by your Sole Proprietor customer is extremely important. All Sole Proprietor Brands must be OTP-verified by July 5, 2023 to avoid filtering on the 10DLC phone numbers associated with their Campaign.
Effective July 5, 2023, all 10DLC phone numbers used to send SMS and MMS messages to U.S. phone numbers must be fully registered to an approved A2P campaign. Messages sent using unregistered phone numbers will be subject to a gradual increase of message blocking by Twilio, beginning on July 5, 2023, ultimately leading to a full block of all unregistered U.S.-bound messages sent after August 31, 2023. For more information, visit our Shutdown of Unregistered 10DLC Messaging FAQ
2.4 [Optional] Retry OTP Verification for the submitted mobile number
The change from a Sole Proprietor's Brand to the APPROVED
state 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 2.1 to check the OTP verification status.
3. [Optional] Create a new Sole Proprietor Campaign use case
Once you have updated the customer's Sole Proprietor Trust Bundle and verified their Sole Proprietor Brand, you can create a new Sole Proprietor Campaign use case for them if you do not have an existing Sole Proprietor Campaign already. Follow the steps here to complete this process. Once you have created and verified a Sole Proprietor Campaign, your customer will be registered for A2P 10DLC.
If you already have an existing Sole Proprietor Campaign created under this Brand, you may skip this step. Your existing Campaign remain valid, and you can continue to use them to send traffic to the US.
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.