Existing Sole Proprietor US A2P 10DLC Registration for ISVs: API Walkthrough

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:

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:

1. Update the existing Sole Proprietor A2P Trust Bundle with new required information (Brand Name, Mobile Number, and optional Vertical)
2. Update the existing Sole Proprietor A2P Brand (and complete OTP verification)
3. (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.

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

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.

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.

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.