A2P 10DLC - Standard and Low-Volume Standard Brand Onboarding Guide for ISVs

This section covers the prerequisite steps you need to complete before attempting to register your customer for A2P 10DLC via API.

Twilio and TCR need specific information about your customer's business in order to register for A2P 10DLC.

Visit the A2P 10DLC - Gather Business Information page to learn which information you need to collect from your customers.

If you plan to use one of the Helper Libraries for this registration process, be sure you're using the latest version.

Before onboarding your customers, you must have a Primary Business Profile with a Twilio Approved status.

Create your Primary Business Profile in the Trust Hub in the Consolee. Select ISV Reseller or Partner as your Business Type.

Make note of your Primary Business Profile SID. You need it in later steps in this guide.

When making the API requests in this guide, use the Twilio Account SID and Auth Token for the Account your customer will use for A2P 10DLC messaging.

The API requests in this section use the TrustHub API to create a Secondary Customer Profile. This is a collection of contact details and business information about your customer's business, similar to the Primary Business Profile you created earlier.

In Step 1.1 below, you create a CustomerProfile resource (this is the "Secondary Customer Profile").

In Steps 1.2-1.7 below, you create additional resources that contain business information, and then you attach these resources to the CustomeProfile resource.

After attaching all required information to the CustomerProfile, you can check and submit the Secondary Customer Profile for review (Steps 1.9 and 1.10, respectively).

This step creates a CustomerProfile resource for your customer's business.

• Save the sid in the response to this request. This is the SID of the Secondary Customer Profile that you need in subsequent steps.
• Do not change the policy_sid in the API request below. This is the Policy (rule set) that defines which information is required for a CustomerProfile.
• The friendly_name is an internal identifier for this Customer Profile. Use a descriptive name that you understand, e.g., "Acme, Inc. Secondary Customer Profile".
• The email parameter is the email address that will receive updates when the CustomerProfile resource's status changes. This should not be your customer's email address. This is an email address that you (as the ISV) own, since you need to monitor this CustomerProfile resource's status as part of the onboarding process.
• The status_callback parameter is optional. This is the URL to which Twilio sends updates regarding this CustomerProfile's status .

This step creates an EndUser resource containing your customer's business information.

• The type parameter must be "customer_profile_business_information" .
• The friendly_name is an internal name for this API resource. Use a descriptive name, e.g., "Acme, Inc. Business Information EndUser resource".
• All of the specific business information is passed in within the attributes parameter, as an object.
  • The attributes object contains the following parameters and the corresponding values that you collected from your customer earlier:
    • business_identity
    • business_industry
    • business_name
    • business_regions_of_operation
    • business_registration_identifier
    • business_registration_number
    • business_type
    • social_media_profile_urls (optional)
    • website_url
• Save the sid in the response of this API request, which starts with "IT". You need it in the next step.

This step associates the EndUser resource with the Secondary Customer Profile from Step 1.1.

• The sid in the path of this request is the SID of the CustomerProfile resource from Step 1.1.
• The object_sid is the EndUser resource SID from Step 1.2.

This step provides required information about an authorized representative for your customer's business.

• The type parameter has a value of "authorized_representative_1" .
• The friendly_name is an internal name for identifying this EndUser resource. Use a descriptive name, e.g., "Acme, Inc. Authorized Rep 1".
• The authorized representative's contact information is provided via the attributes parameter. The attributes object contains the following parameters and the corresponding values that you collected from your customer earlier:
  • business_title
  • email
  • first_name
  • job_position
  • last_name
  • phone_number

You may provide a second authorized representative by repeating this request, but use authorized_representative_2 for the type parameter instead. You must also complete the next step again, but with the SID associated with the authorized_representative_2 EndUser.

• The sid in the path of this request is the SID of the Secondary Customer Profile from Step 1.1.
• The object_sid is the EndUser resource SID from Step 1.4.

This API request creates an Address resource containing your customer's mailing address.

• The friendly_name is an internal name. Use something descriptive, e.g., "Acme, Inc. Address".
• This request also uses the following parameters and the corresponding values that you collected from your customer earlier:
  • city
  • customer_name
  • iso_country
  • postal_code
  • region
  • street
  • street_secondary (optional)
• Save the sid in the response to this request. You need it in the next step.

This step creates a SupportingDocument resource, which is how the TrustHub API stores the Address information.

• The friendly_name is an internal name. Use something descriptive, e.g., "Acme, Inc. Address SupportingDocument".
• The type parameter must be customer_profile_address .
• The attributes parameter is an object with a property of address_sids . The value of this property is the Address SID from the previous step.
• Save the sid in the response to this API request. You need it in the next step.

This step associates the SupportingDocument resource with your customer's Secondary Customer Profile.

• The sid in the path of this request is the SID of the Secondary Customer Profile from 1.1.
• The object_sid is the SupportingDocument resource SID from Step 7.

This API request runs an automated evaluation on the Secondary Customer Profile. The response from Twilio indicates whether or not all required information (as per the Policy) is present in the Secondary Customer Profile.

If there are no errors, the response contains a status of compliant. Otherwise, the status is noncompliant and the results property contains information about invalid or missing information.

• The customer_profile_sid is the SID of the Secondary Customer Profile.
• The policy_sid is RNdfbf3fae0e1107f8aded0e7cead80bf5 .

This API request submits the Secondary Customer Profile for review.

• The sid is the SID of the Secondary Customer Profile.
• The status must be pending_review .

After submitting, you can proceed to the next step. The Secondary Customer Profile does not need to have an approved status in order to continue.

This section of the onboarding guide covers creating and submitting a TrustProduct resource via the TrustHub API. This TrustProduct is a "container" for some additional business information that TCR requires.

In Step 2.1 below, you create the TrustProduct resource. Next, you provide the additional business information in an EndUser resource (Step 2.2) and then attach the EndUser resource to the TrustProuduct in Step 2.3. In Step 2.4, you attach the CustomerProfile resource to the TrustProduct resource. Finally, you check and submit the TrustProduct for review in Steps 2.5 and 2.6.

This step creates a TrustProduct resource, which is a "container" for some additional business information that TCR requires.

• The friendly_name is an internal name. Use something descriptive, e.g., "Acme, Inc. A2P Trust Product".
• The email is the email address to which Twilio sends updates when the TrustProduct's status changes. This should be your (the ISV's) email address, not the customer's . You need to monitor this email address for changes in the TrustProduct's status .
• The policy_sid must be RNb0d4771c2c98518d916a3d4cd70a8f8b
• The status_callback is the URL to which Twilio sends status updates about the TrustProduct. This is optional, but recommended.
• Save the sid returned by this request. You need it in later steps.

This step creates an EndUser resource that contains the additional information required by TCR.

• The type parameter must be us_a2p_messaging_profile_information .
• The friendly-name is an internal name. Use something descriptive, e.g., "Acme, Inc. Messaging Profile EndUser".
• All of the specific business information is passed in within the attributes parameter, as an object.
  • The attributes object contains the following parameters and the corresponding values that you collected from your customer earlier:
    • company_type
    • stock_exchange (if applicable)
    • stock_ticker (if applicable)
  • If the company_type is anything other than public , omit the stock_ticker and stock_exchange properties.

The example below shows a request for creating this EndUser resource for a public company.

This step attaches the EndUser resource to the TrustProduct resource.

• The sid in the path of this request is the SID of the TrustProduct.
• The object_sid is the EndUser resource SID from the previous step.

This step attaches the CustomerProfile resource to the TrustProduct.

• The sid in the path of this request is the SID of the TrustProduct.
• The object_sid is the SID of the Secondary Customer Profile from Step 1.1.

This API request runs an automated evaluation on the TrustProduct. The response from Twilio indicates whether or not all required information (as per the Policy) is present in the TrustProduct.

If there are no errors, the response contains a status of compliant. Otherwise, the status is noncompliant and the results property contains information about invalid or missing information.

• The trust_product_sid is the SID of the TrustProduct.
• The policy_sid must be RNb0d4771c2c98518d916a3d4cd70a8f8b .

Address any errors before continuing to the next step.

This API request submits the TrustProduct for review.

• The sid is the SID of the TrustProduct.
• The status must be pending_review .

Continue to the next step. You don't need to wait for this TrustProduct's status to be approved.

This API request creates a BrandRegistration resource, which represents your customer's Brand. Creating the BrandRegistration resource submits all of the Brand-related information for vetting by TCR.

• The customer_profile_bundle_sid is the SID of your customer's Secondary Customer Profile.
• The a2p_profile_bundle_sid is the SID of the TrustProduct created in Step 2.1.
• skip_automatic_sec_vet is an optional Boolean. You should omit this parameter unless you know the Brand should skip secondary vetting. Read the A2P 10DLC - Gather Business Information page for more details.

The example below shows how to skip secondary vetting for the Brand. (Only for Low-Volume Standard Brands and 527 Political organizations)

Save the sid from the response. You need this in a later step.

Your customer needs a Messaging Service through which it handles its A2P 10DLC messaging.

This section covers the creation of a new Messaging Service. You should create a new Messaging Service for A2P 10DLC rather than reuse an existing one.

Save the SID returned by this request; you need it in a later step. You can also find Messaging Service SIDs in the Console or by using the Read multiple Service resources API request.

This request creates an unconfigured Messaging Service. Read the Messaging Service docs to learn more about how to configure a Messaging Service.

This section covers the creation of a UsAppToPerson resource, which contains the information about the business' messaging Campaign and Use Case.

Once a BrandRegistration's status is approved, you can find out which Use Cases are available for your customer. The API request below returns all of the possible A2P Use Cases that your customer's Brand can use for an A2P Campaign.

• The messaging_service_sid is the SID of the Messaging Service from Step 4 above.
• The brand_registration_sid is the SID of the BrandRegistration resource you created in Step 3.

Choose the Use Case that best aligns with your customer's business needs. This is used in the next step.

This step creates the UsAppToPerson resource. When you create this resource, you provide details about your customer's Campaign, such as how message recipients opt in and out, ask for help, and what the messages typically contain.

The example below shows a sample request for businesses that are using Twilio's default opt-out behavior or Advanced Opt-out feature.

Businesses managing their own opt-out, opt-in, and help keywords need to provide additional information when registering a Campaign. Check out the UsAppToPerson resource doc for an example.

For more details on the format and contents of each parameter, visit the A2P 10DLC - Gather Business Information page.

Before your customer can begin sending A2P 10DLC messages, a 10DLC number must be added to the Messaging Service. Read the Messaging Service PhoneNumber resource doc for more information.

Fetch a Campaign - Use this API request to check a Campaign's registration status.

Subscribe to a Campaign's status using Event Streams - Set up your own endpoint and subscribe to Brand, Campaign, and 10DLC Phone Number status updates from Twilio.

Delete a UsAppToPerson resource - This API request deletes a Campaign and removes it from a Messaging Service.

Troubleshooting A2P 10DLC Registrations - Learn how to understand registration failures and how to fix them.

A2P 10DLC Campaign Approval Best Practices - Ensure your Campaigns meet all requirements.

Trust Hub API Docs - Read the API documentation for CustomerProfiles, EndUsers, TrustProducts, and SupportingDocuments.