This is a step-by-step walkthrough for Independent Software Vendors (ISVs) who wish to use Twilio's REST API to register a customer for a Standard Brand or Low-Volume Brand for A2P 10DLC.
Not sure if you're an ISV? Check out the Determine your customer type section on the A2P 10DLC Overview Page.
The onboarding process involves the following main steps:
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 Console. 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.
If you've already registered customers within TrustHub for SHAKEN/STIR, Branded Calls, or CNAM, your customer may already have a Secondary Customer Profile.
You can check for Secondary Customer Profiles in the Console (Account > Customer Profiles). You can use the TrustHub REST API list all CustomerProfile resources associated with your Account.
sid
in the response to this request. This is the SID of the Secondary Customer Profile that you need in subsequent steps.
policy_sid
in the API request below. This is the
Policy
(rule set) that defines which information is required for a CustomerProfile.
friendly_name
is an internal identifier for this Customer Profile. Use a descriptive name that you understand, e.g., "Acme, Inc. Secondary Customer Profile".
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.
status_callback
parameter is optional. This is the URL to which Twilio sends updates regarding this CustomerProfile's
status
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCustomerProfile() {11const customerProfile = await client.trusthub.v1.customerProfiles.create({12email: "acme-inc@example.com",13friendlyName: "Acme, Inc. Secondary Customer Profile",14policySid: "RNdfbf3fae0e1107f8aded0e7cead80bf5",15statusCallback: "https://www.example.com/status-callback-endpoint",16});1718console.log(customerProfile.sid);19}2021createCustomerProfile();
1{2"sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNdfbf3fae0e1107f8aded0e7cead80bf5",5"friendly_name": "Acme, Inc. Secondary Customer Profile",6"status": "draft",7"email": "acme-inc@example.com",8"status_callback": "https://www.example.com/status-callback-endpoint",9"valid_until": null,10"date_created": "2019-07-30T22:29:24Z",11"date_updated": "2019-07-31T01:09:00Z",12"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"links": {14"customer_profiles_entity_assignments": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",15"customer_profiles_evaluations": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",16"customer_profiles_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"17},18"errors": null19}
This step creates an EndUser resource containing your customer's business information.
type
parameter must be
"customer_profile_business_information"
.
friendly_name
is an internal name for this API resource. Use a descriptive name, e.g., "Acme, Inc. Business Information EndUser resource".
attributes
parameter, as an object.
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
sid
in the response of this API request, which starts with "IT". You need it in the next step.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createEndUser() {11const endUser = await client.trusthub.v1.endUsers.create({12attributes: {13business_name: "Acme, Inc.",14social_media_profile_urls:15"https://example.com/acme-social-media-profile",16website_url: "https://www.example.com",17business_regions_of_operation: "USA_AND_CANADA",18business_type: "Partnership",19business_registration_identifier: "EIN",20business_identity: "direct_customer",21business_industry: "EDUCATION",22business_registration_number: "123456789",23},24friendlyName: "Acme, Inc. - Business Information EndUser resource",25type: "customer_profile_business_information",26});2728console.log(endUser.sid);29}3031createEndUser();
1{2"date_updated": "2021-02-16T20:40:57Z",3"sid": "ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"friendly_name": "Acme, Inc. - Business Information EndUser resource",5"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"url": "https://trusthub.twilio.com/v1/EndUsers/ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"date_created": "2021-02-16T20:40:57Z",8"attributes": {9"phone_number": "+11234567890",10"job_position": "CEO",11"first_name": "rep1",12"last_name": "test",13"business_title": "ceo",14"email": "foobar@test.com"15},16"type": "customer_profile_business_information"17}
This step associates the EndUser resource with the Secondary Customer Profile from Step 1.1.
sid
in the path of this request is the SID of the CustomerProfile resource from Step 1.1.
object_sid
is the EndUser resource SID from Step 1.2.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCustomerProfileEntityAssignment() {11const customerProfilesEntityAssignment = await client.trusthub.v112.customerProfiles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.customerProfilesEntityAssignments.create({14objectSid: "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(customerProfilesEntityAssignment.sid);18}1920createCustomerProfileEntityAssignment();
1{2"sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"object_sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2019-07-31T02:34:41Z",7"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"8}
sid
in the path of this request is the SID of the Secondary Customer Profile from Step 1.1.
object_sid
is the EndUser resource SID from Step 1.4.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCustomerProfileEntityAssignment() {11const customerProfilesEntityAssignment = await client.trusthub.v112.customerProfiles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.customerProfilesEntityAssignments.create({14objectSid: "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(customerProfilesEntityAssignment.sid);18}1920createCustomerProfileEntityAssignment();
1{2"sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"object_sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2019-07-31T02:34:41Z",7"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"8}
This API request creates an Address resource containing your customer's mailing address.
friendly_name
is an internal name. Use something descriptive, e.g., "Acme, Inc. Address".
city
customer_name
iso_country
postal_code
region
street
street_secondary
(optional)
sid
in the response to this request. You need it in the next step.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createAddress() {11const address = await client.addresses.create({12city: "San Fransisco",13customerName: "Acme, Inc.",14isoCountry: "US",15postalCode: "12345",16region: "CA",17street: "1234 Market St",18});1920console.log(address.accountSid);21}2223createAddress();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"city": "San Fransisco",4"customer_name": "Acme, Inc.",5"date_created": "Tue, 18 Aug 2015 17:07:30 +0000",6"date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",7"emergency_enabled": false,8"friendly_name": null,9"iso_country": "US",10"postal_code": "12345",11"region": "CA",12"sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"street": "1234 Market St",14"street_secondary": null,15"validated": false,16"verified": false,17"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses/ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"18}
This step creates a SupportingDocument resource, which is how the TrustHub API stores the Address information.
friendly_name
is an internal name. Use something descriptive, e.g., "Acme, Inc. Address SupportingDocument".
type
parameter must be
customer_profile_address
.
attributes
parameter is an object with a property of
address_sids
. The value of this property is the Address SID from the previous step.
sid
in the response to this API request. You need it in the next step.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createSupportingDocument() {11const supportingDocument =12await client.trusthub.v1.supportingDocuments.create({13attributes: {14address_sids: "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15},16friendlyName: "acme",17type: "customer_profile_address",18});1920console.log(supportingDocument.sid);21}2223createSupportingDocument();
1{2"status": "draft",3"date_updated": "2021-02-11T17:23:00Z",4"friendly_name": "acme",5"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"url": "https://trusthub.twilio.com/v1/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"date_created": "2021-02-11T17:23:00Z",8"sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"attributes": {10"address_sids": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"11},12"type": "customer_profile_address",13"mime_type": null14}
This step associates the SupportingDocument resource with your customer's Secondary Customer Profile.
sid
in the path of this request is the SID of the Secondary Customer Profile from 1.1.
object_sid
is the SupportingDocument resource SID from Step 7.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCustomerProfileEntityAssignment() {11const customerProfilesEntityAssignment = await client.trusthub.v112.customerProfiles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.customerProfilesEntityAssignments.create({14objectSid: "RDXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(customerProfilesEntityAssignment.sid);18}1920createCustomerProfileEntityAssignment();
1{2"sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"object_sid": "RDXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2019-07-31T02:34:41Z",7"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"8}
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.
customer_profile_sid
is the SID of the Secondary Customer Profile.
policy_sid
is
RNdfbf3fae0e1107f8aded0e7cead80bf5
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createCustomerProfileEvaluation() {11const customerProfilesEvaluation = await client.trusthub.v112.customerProfiles("BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.customerProfilesEvaluations.create({14policySid: "RNdfbf3fae0e1107f8aded0e7cead80bf5",15});1617console.log(customerProfilesEvaluation.sid);18}1920createCustomerProfileEvaluation();
1{2"sid": "ELaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNdfbf3fae0e1107f8aded0e7cead80bf5",5"customer_profile_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"status": "noncompliant",7"date_created": "2020-04-28T18:14:01Z",8"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations/ELaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"results": [10{11"friendly_name": "Business",12"object_type": "business",13"passed": false,14"failure_reason": "A Business End-User is missing. Please add one to the regulatory bundle.",15"error_code": 22214,16"valid": [],17"invalid": [18{19"friendly_name": "Business Name",20"object_field": "business_name",21"failure_reason": "The Business Name is missing. Please enter in a Business Name on the Business information.",22"error_code": 2221523},24{25"friendly_name": "Business Registration Number",26"object_field": "business_registration_number",27"failure_reason": "The Business Registration Number is missing. Please enter in a Business Registration Number on the Business information.",28"error_code": 2221529},30{31"friendly_name": "First Name",32"object_field": "first_name",33"failure_reason": "The First Name is missing. Please enter in a First Name on the Business information.",34"error_code": 2221535},36{37"friendly_name": "Last Name",38"object_field": "last_name",39"failure_reason": "The Last Name is missing. Please enter in a Last Name on the Business information.",40"error_code": 2221541}42],43"requirement_friendly_name": "Business",44"requirement_name": "business_info"45},46{47"friendly_name": "Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative",48"object_type": "commercial_registrar_excerpt",49"passed": false,50"failure_reason": "An Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative is missing. Please add one to the regulatory bundle.",51"error_code": 22216,52"valid": [],53"invalid": [54{55"friendly_name": "Business Name",56"object_field": "business_name",57"failure_reason": "The Business Name is missing. Or, it does not match the Business Name you entered within Business information. Please enter in the Business Name shown on the Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative or make sure both Business Name fields use the same exact inputs.",58"error_code": 2221759}60],61"requirement_friendly_name": "Business Name",62"requirement_name": "business_name_info"63},64{65"friendly_name": "Excerpt from the commercial register showing French address",66"object_type": "commercial_registrar_excerpt",67"passed": false,68"failure_reason": "An Excerpt from the commercial register showing French address is missing. Please add one to the regulatory bundle.",69"error_code": 22216,70"valid": [],71"invalid": [72{73"friendly_name": "Address sid(s)",74"object_field": "address_sids",75"failure_reason": "The Address is missing. Please enter in the address shown on the Excerpt from the commercial register showing French address.",76"error_code": 2221977}78],79"requirement_friendly_name": "Business Address (Proof of Address)",80"requirement_name": "business_address_proof_info"81},82{83"friendly_name": "Excerpt from the commercial register (Extrait K-bis)",84"object_type": "commercial_registrar_excerpt",85"passed": false,86"failure_reason": "An Excerpt from the commercial register (Extrait K-bis) is missing. Please add one to the regulatory bundle.",87"error_code": 22216,88"valid": [],89"invalid": [90{91"friendly_name": "Document Number",92"object_field": "document_number",93"failure_reason": "The Document Number is missing. Please enter in the Document Number shown on the Excerpt from the commercial register (Extrait K-bis).",94"error_code": 2221795}96],97"requirement_friendly_name": "Business Registration Number",98"requirement_name": "business_reg_no_info"99},100{101"friendly_name": "Government-issued ID",102"object_type": "government_issued_document",103"passed": false,104"failure_reason": "A Government-issued ID is missing. Please add one to the regulatory bundle.",105"error_code": 22216,106"valid": [],107"invalid": [108{109"friendly_name": "First Name",110"object_field": "first_name",111"failure_reason": "The First Name is missing. Or, it does not match the First Name you entered within Business information. Please enter in the First Name shown on the Government-issued ID or make sure both First Name fields use the same exact inputs.",112"error_code": 22217113},114{115"friendly_name": "Last Name",116"object_field": "last_name",117"failure_reason": "The Last Name is missing. Or, it does not match the Last Name you entered within Business information. Please enter in the Last Name shown on the Government-issued ID or make sure both Last Name fields use the same exact inputs.",118"error_code": 22217119}120],121"requirement_friendly_name": "Name of Authorized Representative",122"requirement_name": "name_of_auth_rep_info"123},124{125"friendly_name": "Executed Copy of Power of Attorney",126"object_type": "power_of_attorney",127"passed": false,128"failure_reason": "An Executed Copy of Power of Attorney is missing. Please add one to the regulatory bundle.",129"error_code": 22216,130"valid": [],131"invalid": [],132"requirement_friendly_name": "Power of Attorney",133"requirement_name": "power_of_attorney_info"134},135{136"friendly_name": "Government-issued ID",137"object_type": "government_issued_document",138"passed": false,139"failure_reason": "A Government-issued ID is missing. Please add one to the regulatory bundle.",140"error_code": 22216,141"valid": [],142"invalid": [143{144"friendly_name": "First Name",145"object_field": "first_name",146"failure_reason": "The First Name is missing on the Governnment-Issued ID.",147"error_code": 22217148},149{150"friendly_name": "Last Name",151"object_field": "last_name",152"failure_reason": "The Last Name is missing on the Government-issued ID",153"error_code": 22217154}155],156"requirement_friendly_name": "Name of Person granted the Power of Attorney",157"requirement_name": "name_in_power_of_attorney_info"158}159]160}
This API request submits the Secondary Customer Profile for review.
sid
is the SID of the Secondary Customer Profile.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateCustomerProfile() {11const customerProfile = await client.trusthub.v112.customerProfiles("BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.update({ status: "pending-review" });1415console.log(customerProfile.sid);16}1718updateCustomerProfile();
1{2"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"friendly_name": "friendly_name",6"status": "pending-review",7"email": "email",8"status_callback": "http://www.example.com",9"valid_until": null,10"date_created": "2019-07-30T22:29:24Z",11"date_updated": "2019-07-31T01:09:00Z",12"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"links": {14"customer_profiles_entity_assignments": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",15"customer_profiles_evaluations": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",16"customer_profiles_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"17},18"errors": null19}
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.
friendly_name
is an internal name. Use something descriptive, e.g., "Acme, Inc. A2P Trust Product".
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
.
policy_sid
must be
RNb0d4771c2c98518d916a3d4cd70a8f8b
status_callback
is the URL to which Twilio sends status updates about the TrustProduct. This is optional, but recommended.
sid
returned by this request. You need it in later steps.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTrustProduct() {11const trustProduct = await client.trusthub.v1.trustProducts.create({12email: "ceo@example.com",13friendlyName: "Acme, Inc. A2P Trust Product",14policySid: "RNb0d4771c2c98518d916a3d4cd70a8f8b",15});1617console.log(trustProduct.sid);18}1920createTrustProduct();
1{2"sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNb0d4771c2c98518d916a3d4cd70a8f8b",5"friendly_name": "Acme, Inc. A2P Trust Product",6"status": "draft",7"email": "ceo@example.com",8"status_callback": "http://www.example.com",9"valid_until": null,10"date_created": "2019-07-30T22:29:24Z",11"date_updated": "2019-07-31T01:09:00Z",12"url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"links": {14"trust_products_entity_assignments": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",15"trust_products_evaluations": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",16"trust_products_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"17},18"errors": null19}
This step creates an EndUser resource that contains the additional information required by TCR.
type
parameter must be
us_a2p_messaging_profile_information
.
friendly-name
is an internal name. Use something descriptive, e.g., "Acme, Inc. Messaging Profile EndUser".
attributes
parameter, as an object.
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)
company_type
is anything other than
public
, omit the
stock_ticker
and
stock_exchange
properties.
brand_contact_email
needs to be provided as part of brand regstriation where a 2FA email will be sent for the brand contact to verify for public, for profit brands.
The example below shows a request for creating this EndUser resource for a public company.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createEndUser() {11const endUser = await client.trusthub.v1.endUsers.create({12attributes: {13company_type: "public",14stock_exchange: "NYSE",15stock_ticker: "ACME",16},17friendlyName: "Acme, Inc. Messaging Profile EndUser",18type: "us_a2p_messaging_profile_information",19});2021console.log(endUser.sid);22}2324createEndUser();
1{2"date_updated": "2021-02-16T20:40:57Z",3"sid": "ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"friendly_name": "Acme, Inc. Messaging Profile EndUser",5"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"url": "https://trusthub.twilio.com/v1/EndUsers/ITaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"date_created": "2021-02-16T20:40:57Z",8"attributes": {9"phone_number": "+11234567890",10"job_position": "CEO",11"first_name": "rep1",12"last_name": "test",13"business_title": "ceo",14"email": "foobar@test.com"15},16"type": "us_a2p_messaging_profile_information"17}
This step attaches the EndUser resource to the TrustProduct resource.
sid
in the path of this request is the SID of the TrustProduct.
object_sid
is the EndUser resource SID from the previous step.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTrustProductEntityAssignment() {11const trustProductsEntityAssignment = await client.trusthub.v112.trustProducts("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.trustProductsEntityAssignments.create({14objectSid: "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(trustProductsEntityAssignment.sid);18}1920createTrustProductEntityAssignment();
1{2"sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"object_sid": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2019-07-31T02:34:41Z",7"url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"8}
This step attaches the CustomerProfile resource to the TrustProduct.
sid
in the path of this request is the SID of the TrustProduct.
object_sid
is the SID of the Secondary Customer Profile from Step 1.1.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTrustProductEntityAssignment() {11const trustProductsEntityAssignment = await client.trusthub.v112.trustProducts("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.trustProductsEntityAssignments.create({14objectSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(trustProductsEntityAssignment.sid);18}1920createTrustProductEntityAssignment();
1{2"sid": "BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"object_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2019-07-31T02:34:41Z",7"url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments/BVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"8}
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.
trust_product_sid
is the SID of the TrustProduct.
policy_sid
must be
RNb0d4771c2c98518d916a3d4cd70a8f8b
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTrustProductEvaluation() {11const trustProductsEvaluation = await client.trusthub.v112.trustProducts("BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.trustProductsEvaluations.create({14policySid: "RNb0d4771c2c98518d916a3d4cd70a8f8b",15});1617console.log(trustProductsEvaluation.sid);18}1920createTrustProductEvaluation();
1{2"sid": "ELaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNb0d4771c2c98518d916a3d4cd70a8f8b",5"trust_product_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"status": "noncompliant",7"date_created": "2020-04-28T18:14:01Z",8"url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations/ELaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"results": [10{11"friendly_name": "Business",12"object_type": "business",13"passed": false,14"failure_reason": "A Business End-User is missing. Please add one to the regulatory bundle.",15"error_code": 22214,16"valid": [],17"invalid": [18{19"friendly_name": "Business Name",20"object_field": "business_name",21"failure_reason": "The Business Name is missing. Please enter in a Business Name on the Business information.",22"error_code": 2221523},24{25"friendly_name": "Business Registration Number",26"object_field": "business_registration_number",27"failure_reason": "The Business Registration Number is missing. Please enter in a Business Registration Number on the Business information.",28"error_code": 2221529},30{31"friendly_name": "First Name",32"object_field": "first_name",33"failure_reason": "The First Name is missing. Please enter in a First Name on the Business information.",34"error_code": 2221535},36{37"friendly_name": "Last Name",38"object_field": "last_name",39"failure_reason": "The Last Name is missing. Please enter in a Last Name on the Business information.",40"error_code": 2221541}42],43"requirement_friendly_name": "Business",44"requirement_name": "business_info"45},46{47"friendly_name": "Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative",48"object_type": "commercial_registrar_excerpt",49"passed": false,50"failure_reason": "An Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative is missing. Please add one to the regulatory bundle.",51"error_code": 22216,52"valid": [],53"invalid": [54{55"friendly_name": "Business Name",56"object_field": "business_name",57"failure_reason": "The Business Name is missing. Or, it does not match the Business Name you entered within Business information. Please enter in the Business Name shown on the Excerpt from the commercial register (Extrait K-bis) showing name of Authorized Representative or make sure both Business Name fields use the same exact inputs.",58"error_code": 2221759}60],61"requirement_friendly_name": "Business Name",62"requirement_name": "business_name_info"63},64{65"friendly_name": "Excerpt from the commercial register showing French address",66"object_type": "commercial_registrar_excerpt",67"passed": false,68"failure_reason": "An Excerpt from the commercial register showing French address is missing. Please add one to the regulatory bundle.",69"error_code": 22216,70"valid": [],71"invalid": [72{73"friendly_name": "Address sid(s)",74"object_field": "address_sids",75"failure_reason": "The Address is missing. Please enter in the address shown on the Excerpt from the commercial register showing French address.",76"error_code": 2221977}78],79"requirement_friendly_name": "Business Address (Proof of Address)",80"requirement_name": "business_address_proof_info"81},82{83"friendly_name": "Excerpt from the commercial register (Extrait K-bis)",84"object_type": "commercial_registrar_excerpt",85"passed": false,86"failure_reason": "An Excerpt from the commercial register (Extrait K-bis) is missing. Please add one to the regulatory bundle.",87"error_code": 22216,88"valid": [],89"invalid": [90{91"friendly_name": "Document Number",92"object_field": "document_number",93"failure_reason": "The Document Number is missing. Please enter in the Document Number shown on the Excerpt from the commercial register (Extrait K-bis).",94"error_code": 2221795}96],97"requirement_friendly_name": "Business Registration Number",98"requirement_name": "business_reg_no_info"99},100{101"friendly_name": "Government-issued ID",102"object_type": "government_issued_document",103"passed": false,104"failure_reason": "A Government-issued ID is missing. Please add one to the regulatory bundle.",105"error_code": 22216,106"valid": [],107"invalid": [108{109"friendly_name": "First Name",110"object_field": "first_name",111"failure_reason": "The First Name is missing. Or, it does not match the First Name you entered within Business information. Please enter in the First Name shown on the Government-issued ID or make sure both First Name fields use the same exact inputs.",112"error_code": 22217113},114{115"friendly_name": "Last Name",116"object_field": "last_name",117"failure_reason": "The Last Name is missing. Or, it does not match the Last Name you entered within Business information. Please enter in the Last Name shown on the Government-issued ID or make sure both Last Name fields use the same exact inputs.",118"error_code": 22217119}120],121"requirement_friendly_name": "Name of Authorized Representative",122"requirement_name": "name_of_auth_rep_info"123},124{125"friendly_name": "Executed Copy of Power of Attorney",126"object_type": "power_of_attorney",127"passed": false,128"failure_reason": "An Executed Copy of Power of Attorney is missing. Please add one to the regulatory bundle.",129"error_code": 22216,130"valid": [],131"invalid": [],132"requirement_friendly_name": "Power of Attorney",133"requirement_name": "power_of_attorney_info"134},135{136"friendly_name": "Government-issued ID",137"object_type": "government_issued_document",138"passed": false,139"failure_reason": "A Government-issued ID is missing. Please add one to the regulatory bundle.",140"error_code": 22216,141"valid": [],142"invalid": [143{144"friendly_name": "First Name",145"object_field": "first_name",146"failure_reason": "The First Name is missing on the Governnment-Issued ID.",147"error_code": 22217148},149{150"friendly_name": "Last Name",151"object_field": "last_name",152"failure_reason": "The Last Name is missing on the Government-issued ID",153"error_code": 22217154}155],156"requirement_friendly_name": "Name of Person granted the Power of Attorney",157"requirement_name": "name_in_power_of_attorney_info"158}159]160}
Address any errors before continuing to the next step.
This API request submits the TrustProduct for review.
sid
is the SID of the TrustProduct.
status
must be
pending_review
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateTrustProduct() {11const trustProduct = await client.trusthub.v112.trustProducts("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({ status: "pending-review" });1415console.log(trustProduct.sid);16}1718updateTrustProduct();
1{2"sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"policy_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"friendly_name": "friendly_name",6"status": "pending-review",7"email": "email",8"status_callback": "http://www.example.com",9"valid_until": null,10"date_created": "2019-07-30T22:29:24Z",11"date_updated": "2019-07-31T01:09:00Z",12"url": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"links": {14"trust_products_entity_assignments": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/EntityAssignments",15"trust_products_evaluations": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",16"trust_products_channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments"17},18"errors": null19}
Continue to the next step. You don't need to wait for this TrustProduct's status
to be approved
.
Please rate limit all API requests for Brand and Campaign registration to one request per second.
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.
This API request incurs fees on your Twilio Account. Learn more about A2P 10DLC registration fees in the What pricing and fees are associated with the A2P 10DLC service? Help Center article.
customer_profile_bundle_sid
is the SID of your customer's Secondary Customer Profile.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createBrandRegistrations() {11const brandRegistration = await client.messaging.v1.brandRegistrations.create(12{13a2PProfileBundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14customerProfileBundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15}16);1718console.log(brandRegistration.sid);19}2021createBrandRegistrations();
1{2"sid": "BN0044409f7e067e279523808d267e2d85",3"account_sid": "AC78e8e67fc0246521490fb9907fd0c165",4"customer_profile_bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"a2p_profile_bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2021-01-28T10:45:51Z",7"date_updated": "2021-01-28T10:45:51Z",8"brand_type": "STANDARD",9"status": "PENDING",10"tcr_id": "BXXXXXX",11"failure_reason": "Registration error",12"url": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85",13"brand_score": 42,14"brand_feedback": [15"TAX_ID",16"NONPROFIT"17],18"identity_status": "VERIFIED",19"russell_3000": true,20"government_entity": false,21"tax_exempt_status": "501c3",22"skip_automatic_sec_vet": false,23"errors": [],24"mock": false,25"links": {26"brand_vettings": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85/Vettings",27"brand_registration_otps": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85/SmsOtp"28}29}
The example below shows how to skip secondary vetting for the Brand. (Only for Low-Volume Standard Brands and 527 Political organizations)
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createBrandRegistrations() {11const brandRegistration = await client.messaging.v1.brandRegistrations.create(12{13a2PProfileBundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14customerProfileBundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15skipAutomaticSecVet: true,16}17);1819console.log(brandRegistration.sid);20}2122createBrandRegistrations();
1{2"sid": "BN0044409f7e067e279523808d267e2d85",3"account_sid": "AC78e8e67fc0246521490fb9907fd0c165",4"customer_profile_bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"a2p_profile_bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",6"date_created": "2021-01-28T10:45:51Z",7"date_updated": "2021-01-28T10:45:51Z",8"brand_type": "STANDARD",9"status": "PENDING",10"tcr_id": "BXXXXXX",11"failure_reason": "Registration error",12"url": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85",13"brand_score": 42,14"brand_feedback": [15"TAX_ID",16"NONPROFIT"17],18"identity_status": "VERIFIED",19"russell_3000": true,20"government_entity": false,21"tax_exempt_status": "501c3",22"skip_automatic_sec_vet": true,23"errors": [],24"mock": false,25"links": {26"brand_vettings": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85/Vettings",27"brand_registration_otps": "https://messaging.twilio.com/v1/a2p/BrandRegistrations/BN0044409f7e067e279523808d267e2d85/SmsOtp"28}29}
Save the sid
from the response. You need this in a later step.
Sometimes, Brand vetting by TCR can take several days.
If the BrandRegistration resources's status
is IN_REVIEW
for more than two days, contact Support.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createService() {11const service = await client.messaging.v1.services.create({12fallbackUrl: "https://www.example.com/fallback",13friendlyName: "Acme, Inc.'s A2P 10DLC Messaging Service",14inboundRequestUrl: "https://www.example.com/inbound-messages-webhook",15});1617console.log(service.sid);18}1920createService();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"date_created": "2015-07-30T20:12:31Z",5"date_updated": "2015-07-30T20:12:33Z",6"friendly_name": "Acme, Inc.'s A2P 10DLC Messaging Service",7"inbound_request_url": "https://www.example.com/inbound-messages-webhook",8"inbound_method": "POST",9"fallback_url": "https://www.example.com/fallback",10"fallback_method": "GET",11"status_callback": "https://www.example.com",12"sticky_sender": true,13"smart_encoding": false,14"mms_converter": true,15"fallback_to_long_code": true,16"scan_message_content": "inherit",17"area_code_geomatch": true,18"validity_period": 600,19"synchronous_validation": true,20"usecase": "marketing",21"us_app_to_person_registered": false,22"use_inbound_webhook_on_number": true,23"sending_windows": [],24"links": {25"phone_numbers": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",26"short_codes": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes",27"alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AlphaSenders",28"messages": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",29"us_app_to_person": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p",30"us_app_to_person_usecases": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/Usecases",31"channel_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelSenders"32},33"url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"34}
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.
Do not continue to the next step until the BrandRegistration's status
is APPROVED
.
This section covers the creation of a UsAppToPerson resource, which contains the information about the business' messaging Campaign and Use Case.
Do not complete this section until the BrandRegistration's status
is APPROVED
.
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.
messaging_service_sid
is the SID of the Messaging Service from Step 4 above.
brand_registration_sid
is the SID of the BrandRegistration resource you created in Step 3.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchUsAppToPersonUsecase() {11const usAppToPersonUsecase = await client.messaging.v112.services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.usAppToPersonUsecases.fetch({14brandRegistrationSid: "BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15});1617console.log(usAppToPersonUsecase.usAppToPersonUsecases);18}1920fetchUsAppToPersonUsecase();
1{2"us_app_to_person_usecases": [3{4"code": "2FA",5"name": "Two-Factor authentication (2FA)",6"description": "Two-Factor authentication, one-time use password, password reset",7"post_approval_required": false8},9{10"code": "ACCOUNT_NOTIFICATION",11"name": "Account Notification",12"description": "All reminders, alerts, and notifications. (Examples include: flight delayed, hotel booked, appointment reminders.)",13"post_approval_required": false14},15{16"code": "AGENTS_FRANCHISES",17"name": "Agents and Franchises",18"description": "For brands that have multiple agents, franchises or offices in the same brand vertical, but require individual localised numbers per agent/location/office.",19"post_approval_required": true20},21{22"code": "CHARITY",23"name": "Charity",24"description": "Includes: 5013C Charity\nDoes not include: Religious organizations",25"post_approval_required": false26},27{28"code": "PROXY",29"name": "Proxy",30"description": "Peer-to-peer app-based group messaging with proxy/pooled numbers (For example: GroupMe)\nSupporting personalized services and non-exposure of personal numbers for enterprise or A2P communications. (Examples include: Uber and AirBnb.)",31"post_approval_required": true32},33{34"code": "CUSTOMER_CARE",35"name": "Customer Care",36"description": "All customer care messaging, including account management and support",37"post_approval_required": false38},39{40"code": "DELIVERY_NOTIFICATION",41"name": "Delivery Notification",42"description": "Information about the status of the delivery of a product or service",43"post_approval_required": false44},45{46"code": "EMERGENCY",47"name": "Emergency",48"description": "Notification services designed to support public safety / health during natural disasters, armed conflicts, pandemics and other national or regional emergencies",49"post_approval_required": true50},51{52"code": "FRAUD_ALERT",53"name": "Fraud Alert Messaging",54"description": "Fraud alert notification",55"post_approval_required": false56},57{58"code": "HIGHER_EDUCATION",59"name": "Higher Education",60"description": "For campaigns created on behalf of Colleges or Universities and will also include School Districts etc that fall outside of any \"free to the consumer\" messaging model",61"post_approval_required": false62},63{64"code": "K12_EDUCATION",65"name": "K-12 Education",66"description": "Campaigns created for messaging platforms that support schools from grades K-12 and distance learning centers. This is not for Post-Secondary schools.",67"post_approval_required": true68},69{70"code": "LOW_VOLUME",71"name": "Low Volume Mixed",72"description": "Low throughput, any combination of use-cases. Examples include: test, demo accounts",73"post_approval_required": false74},75{76"code": "MARKETING",77"name": "Marketing",78"description": "Any communication with marketing and/or promotional content",79"post_approval_required": false80},81{82"code": "MIXED",83"name": "Mixed",84"description": "Mixed messaging reserved for specific consumer service industry",85"post_approval_required": false86},87{88"code": "POLITICAL",89"name": "Political",90"description": "Part of organized effort to influence decision making of specific group. All campaigns to be verified",91"post_approval_required": false92},93{94"code": "POLLING_VOTING",95"name": "Polling and voting",96"description": "Polling and voting",97"post_approval_required": false98},99{100"code": "PUBLIC_SERVICE_ANNOUNCEMENT",101"name": "Public Service Announcement",102"description": "An informational message that is meant to raise the audience awareness about an important issue",103"post_approval_required": false104},105{106"code": "SECURITY_ALERT",107"name": "Security Alert",108"description": "A notification that the security of a system, either software or hardware, has been compromised in some way and there is an action you need to take",109"post_approval_required": false110},111{112"code": "SOCIAL",113"name": "Social",114"description": "Communication within or between closed communities (For example: influencers alerts)",115"post_approval_required": true116},117{118"code": "SWEEPSTAKE",119"name": "Sweepstake",120"description": "Sweepstake",121"post_approval_required": true122}123]124}
Choose the Use Case that best aligns with your customer's business needs. This is used in the next step.