ISV US A2P 10DLC Standard Registration: API Walkthrough

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. This involves three different APIs to cover the main steps of the 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.

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

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:

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.

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:

1.4 Create end-user of type: authorized_representative_1

This step provides required information about an authorized business representative (one authorized point of contact is required) for the secondary customer profile. You may use one point of contact from your own company as the authorized representative across all of your Standard customers for registration purposes.

The email value should be the end-business’s email address and not your ISV's email address.

In this step, there are parameters with multiple valid values:

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:

1.6.1 Create customer document (when you have a valid AddressSID)

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.

1. authorized_representative_1 and optionally authorized_representative_2
2. supporting document (address)
3. customer_profile_business_information
4. 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.

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.

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:

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.

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: To create an A2P brand without Secondary Vetting, see optional Step 3.2.

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:

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:

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

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 Create an A2P Brand without Secondary Vetting

You should skip secondary vetting for one or more of your Secondary Brands (your clients) to register for Low Volume Standard Brands. Set the parameter SkipAutomaticSecVet to true so the brand being submitted will only go through primary vetting (brand registration) 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.

Low Volume Standard Brands will by default receive the following throughput and messaging limits:

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.

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

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.

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

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

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.

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.

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.