Overview
Plivo’s 10DLC API allows customers to complete their 10DLC registration. This guide is for resellers who want to complete 10DLC registration for their customers in the US or Canada who do not have a Tax ID. Plivo recommends creating a starter brand for these customers.
Limitations of starter registration
Starter registration comes with the following limitations.
- Each brand can create up to one campaign. That campaign can only be linked to one US long code.
- Starter registration is only available for customers with a valid US or Canadian address.
- Each starter registration requires a US or Canadian mobile number. Please note that this number cannot be a number acquired by a CPaaS provider like Plivo.
- Duplication checks: The Campaign Registry (TCR) has mandated additional checks on email and mobile phone number fields.
- This mobile number can be only used a maximum of three times across all A2P registrations with TCR. Numbers that have been used with another CPaaS provider count towards this limit.
Cost
Each 10DLC brand registration will cost a one-time fee of $4. Each campaign will cost $2 per month. Additionally, each campaign needs to be vetted, resulting in a one-time fee of $15. Read more about the vetting process here.
Steps
To complete your registration, follow these steps.
- Create a profile with entity_type =
INDIVIDUAL. Profile registration details can be found in our API documentation. - Use your profile to create a 10DLC brand.
- Provide a mobile number to verify your brand creation request.
- Verify your 10DLC brand by responding to the text message received from TCR. If you don’t receive a message, use the Brand API to trigger the verification message again. When you reply to that message, TCR will mark your brand as verified.
- Create your campaign and submit it for approval.
- Once approved, link the number to your campaign.
Create a profile
This API lets you create a business profile for your customers who do not have an EIN.
API Endpoint
POST https://api.plivo.com/v1/Account/{auth_id}/Profile/Arguments
| profile_aliasstringrequired | A friendly name for your profile. |
| customer_typestringrequired | Indicates the nature of your operations. |
| entity_typestringrequired | Indicates ownership of the company. |
| company_namestringrequired | Legal name of the company. |
| vertical stringrequired | Indicates industry. Allowed values: PROFESSIONAL, REAL_ESTATE, HEALTHCARE, HUMAN_RESOURCES, ENERGY,ENTERTAINMENT, RETAIL, TRANSPORTATION,AGRICULTURE,INSURANCE,POSTAL,EDUCATION,HOSPITALITY, FINANCIAL, POLITICAL, GAMBLING, LEGAL, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY, COMMUNICATION |
| address objectrequired | Valid postal address of the company. {"street": "", "city": "", "state": "", "postal_code": "", "country": "" } state: A valid state code, e.g. TX for Texas. |
| authorized_contact objectrequired | Authorized contact person at the company. "first_name": "John", Fields first_name and last_name are free-form. email: Email address.title: Salutation of the contact at the given company. seniority: Allowed values: DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER. phone: Company phone number in E.164 format. |
| website string | Website of the business. |
| plivo_subaccount string | Subaccount mapped to the profile. |
1
2
3
4
5
6
7
8
9
10
11
12
let plivo = require('plivo');
let fs = require('fs');
var authorized_contact = {"first_name":"John", "last_name":"Doe", "email":”xxxx@gmail.com", "title":"Mr", "seniority":"Admin", "phone": "14845355113"}
var address = {"street":"#11, Nashville Street", "city":"Dallas", "state":"TX", "postal_code":"10001", "country":"US"}
var client = new plivo.Client("<auth_id>","<auth_token>");
client.profile.create("sample name"," ","DIRECT","INDIVIDUAL","sample company", "COMMUNICATION", "NONE", "www.samplewebsite.com", address,authorized_contact)
.then(function (response) {
console.log(response);
})
.catch(function (error) {
console.log(error);
});
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
curl -i --user auth_id:auth_token \
-H "Content-Type: application/json" \
-d '{
"profile_alias": "sample name",
"customer_type": "DIRECT",
"entity_type": "INDIVIDUAL",
"company_name": "sample company",
"vertical": "COMMUNICATION",
"alt_business_id_type": "NONE",
"website": "www.samplewebsite.com",
"address": {
"street": "#11, Nashville Street",
"city": "Dallas",
"state": "TX",
"postal_code": "10001",
"country": "US"
},
"authorized_contact": {
"first_name": "John",
"last_name": "Doe",
"email": "xxxx@gmail.com",
"title": "Mr",
"seniority": "Admin",
"phone": "14845355113"
}
}'\
https://api.plivo.com/v1/Account/<auth_id>/Profile/
Was this code helpful
Response
{
"api_id": "cc3a6dca-64a9-11ed-a9a3-0242ac110002",
"message": "Profile created successfully.",
"profile_uuid": "7b8ff904-a1d2-46b2-888d-34d4df4cf95a"
}
Register a starter brand
This API lets you register a starter brand using a pre-existing profile.
API Endpoint
POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/Arguments
| brand_aliasstring | A friendly name for your brand. |
| profile_uuidstringrequired | A unique identifier for the profile that you want to use for creating a brand. The profile should not have been used to create another brand. |
| brand_typestringrequired | Indicates the type of registration. |
| mobile_phonestringrequired | A US or Canadian mobile number which will be used to verify the brand. |
| url string | The fully qualified URL to which status update callbacks for the message should be sent. |
| method string | The HTTP method to be used when calling the URL defined above. Allowed values: GET,POST |
1
2
3
4
5
6
7
8
9
10
let plivo = require('plivo');
let fs = require('fs');
let client = new plivo.Client("<auth_id>", "<auth_token>");
var callback = {"url":"<URL>", "method":"POST"} client.brand.create("<brand_alias>","4364774f-095d-4bc8-a85f-cb53907951XX","STARTER",param = {"mobile_phone" : "+1122334455"},callback)
.then(function (response) {
console.log(JSON.stringify(response));
}).catch(function (error) {
console.log("err");
console.log(error);
});
Was this code helpful
1
2
3
4
5
6
7
8
9
curl -i --user auth_id:auth_token \
-H "Content-Type: application/json" \
-d '{
"brand_alias": "<brand_alias>",
"profile_uuid": "<profile_uuid>",
"brand_type": "STARTER",
"mobile_phone": "+1122334455"
}'\
https://api.plivo.com/v1/Account/<auth_id>/10dlc/Brand/
Was this code helpful
Response
{
"api_id":"bc842da0-bbc4-11ec-9f72-0242ac110002",
"brand_id":"BXXXXXX",
"message":"Request to create brand was received and is being processed."
}
Trigger verification for starter brand
This API lets you trigger a verification message for your starter brand. When you register your brand, TCR will send you a message by default. If you don’t receive the message, you can trigger up to 5 verification messages. The verification message will be in the following format. Verify the message by replying YES.
“Please confirm your registration for US A2P Messaging by replying YES. Msg & data rates may apply.”
Once you respond to the message, you will receive the following message
"Thank you. Your registration has been confirmed."
API Endpoint
POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{Brand_id}/OTPArguments
1
2
3
4
5
6
7
8
9
let plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.brand.trigger_otp('<BRAND_ID>')
.then(function (response) {
console.log(response);
},);
})();
Was this code helpful
1
2
3
curl -i --user auth_id:auth_token \
-d ' '\
https://api.plivo.com/v1/Account/<auth_id>/10dlc/Brand/<BRAND_ID>/OTP/
Was this code helpful
Response
{
"api_id": "4254d08d-ed6f-4aba-abb0-4ff6aXXXXXXX",
"brandId": "BNZXXX",
"message": "Message sent to XXXXXXXX2233, reply YES to confirm registration."
}
Register a starter campaign
Once your brand is verified, you can create one starter campaign. This API lets you register a starter campaign using a pre-existing brand.
API Endpoint
POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/Arguments
| campaign_aliasstringrequired | A friendly name for your campaign. This name appears on the Plivo console. |
| brand_idstringrequired | ID of the for which campaign creation request is being submitted. |
| verticalstringrequired | Indicates the industry specific to the message use case. Allowed values: PROFESSIONAL, REAL_ESTATE, HEALTHCARE,HUMAN_RESOURCES, ENERGY, ENTERTAINMENT, RETAIL, TRANSPORTATION, AGRICULTURE, INSURANCE, POSTAL, EDUCATION, HOSPITALITY, FINANCIAL, POLITICAL, GAMBLING, LEGAL, CONSTRUCTION, NGO,MANUFACTURING, GOVERNMENT, TECHNOLOGY,COMMUNICATION |
| descriptionstringrequired | A brief description of the campaign and how it’s relevant to your business — minimum of 40 characters. |
| usecasestringrequired | Indicates your messaging use case. Allowed values: 2FA, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, LOW_VOLUME, MARKETING, MIXED, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, STARTER. STARTER brands can only use STARTER as their use case.
|
| sample1stringrequired | The content of a sample message that you will send through this campaign. You must provide at least two samples, each with a minimum of 20 characters. |
| sample2stringrequired | The content of the second sample message. |
| subscriber_optinbooleanrequired | A confirmation that you are collecting and processing customer opt-ins. Allowed value: true |
| subscriber_optoutbooleanrequired | A confirmation that you are collecting and processing customer opt-outs. Allowed value: true |
| subscriber_helpbooleanrequired | A confirmation that you have implemented a message reply that tells customers how they can contact the message sender when they reply with the “HELP” keyword. Allowed value: true |
| direct_lendingbooleanrequired | Indicates whether this campaign includes content related to direct lending or other loan arrangements. Allowed values: true, false |
| embedded_linkbooleanrequired | Indicates whether embedded links are being used. Operators do not accept public URL shorteners. Allowed values: true, false |
| embedded_phonebooleanrequired | Indicates whether the campaign is using an embedded phone number other than the required HELP contact number. Allowed values: true, false |
| age_gatedbooleanrequired | Indicates whether the campaign includes any age-gated content as defined by operator and CTIA guidelines. Allowed values: true, false |
| affiliate_marketingbooleanrequired | Indicates whether affiliate marketing was used in the construction of this campaign. Allowed values: true, false |
| sub_usecaseslist | Only applicable when use case is STARTER, MIXED, or LOW_VOLUME. Indicates two to five comma-separated use cases. Allowed values: 2FA, ACCOUNT_NOTIFICATION,CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, MARKETING, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT |
| message_flow stringrequired | Describes how a customer opts in to a campaign, thereby giving consent to the sender to send messages. The message flow must be clear and inform customers about the nature of the campaign. If a campaign supports multiple opt-in mechanisms, you must mention all of them here. Check documentation for samples. |
| help_message stringrequired | Indicates the response to the HELP keyword. It may include the brand name and support contact information. Check documentation for samples. |
| optout_message stringrequired | Indicates the response to the STOP keyword. It must include acknowledgement of the opt-out request and confirmation that no further messages will be sent, and may include the brand name. Check documentation for samples. |
| optin_messagestring | Message sent to subscribers to confirm their opt-in to the campaign. |
| optin_keywordsstring | Opt-in keywords associated with the campaign. If more than one, provide a comma-separated list with no special characters or embedded spaces. |
| help_keywordsstring | Help keywords associated with the campaign, in all capital letters. If more than one, provide a comma-separated list with no special characters or embedded spaces. |
| urlstring | The fully qualified URL to which status update callbacks for the message should be sent. |
| methodstring | The HTTP method to be used when calling the URL defined above. Allowed values: GET, POST |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let plivo = require('plivo');
let fs = require('fs');
let client = new plivo.Client("<auth_id>", "<auth_token>");
var callback = {"url":"<URL>", "method":"POST", "optout_keywords":"NO,STOP", "optin_keywords":"YES, SUBSCRIBE, TRUE", "help_keywords":"HELP,INFO,MORE", "optin_message":"<optin_message>"}
console.log('test');
client.campaign.create("<brand_id>","sample name","COMMUNICATION","STARTER",[
"CUSTOMER_CARE",
"2FA"
],"<description>", false,false,false,false,true,true,true,true, "<sample message 1>", "<sample message 2>","<message_flow>","<help_message>","<optout_message>", callback )
.then(function (response) {
console.log(JSON.stringify(response));
}).catch(function (error) {
console.log("err");
console.log(error);
});
Was this code helpful
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl -i --user auth_id:auth_token \
-H "Content-Type: application/json" \
-d '{
"brand_id": "BNZXXX",
"campaign_alias": "SP-campaign",
"vertical": "TECHNOLOGY",
"usecase": "STARTER",
"sub_usecases": ["2FA", "MARKETING"],
"description": "for creating campaign description should have minimum 40 characteristics to perform the request",
"direct_lending": true,
"affiliate_marketing": true,
"embedded_link": true,
"embedded_phone": true,
"age_gated": true,
"subscriber_optin": true,
"subscriber_optout": true,
"subscriber_help": true,
"sample1": "sample message 1 should have minimum 20 characters",
"sample2": "sample message 2 should have minimum 20 characters",
"url": "http://plivobin.non-prod.plivops.com/16xilyn1",
"method": "POST",
"Message_flow": "message flow is mandatory param and minimum 40 characters",
"Help_message": "send HELP to get more",
"optout_message": "send NO to unsubscribe",
"optin_Keywords" : "YES, SUBSCRIBE, TRUE",
"optout_Keywords" : "NO,STOP",
"optin_message" : "In case you want to use optin",
"help_keywords" : "HELP,INFO,MORE"
}'\
https://api.plivo.com/v1/Account/<Auth_id>/10dlc/Campaign/
Was this code helpful
Response
{
"api_id": "d48b4cf2-64ad-11ed-bba6-0242ac110004",
"campaign_id": "CXXXXX",
"message": "Request to create campaign was received and is being processed."
}
Link number to a starter campaign
This API lets you link a number rented to your account with a pre-existing campaign.
API Endpoint
POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{Campaign_id}/NumberArguments
| numberslistrequired | The numbers you want to link to a campaign. Numbers should be in E.164 format |
| urlstring | Fully qualified URL to which status update callbacks for the message should be sent. |
| methodstring | The HTTP method to be used when calling the URL defined above. Allowed values: GET, POST Defaults to POST. |
1
2
3
4
5
6
7
8
9
10
11
12
let plivo = require('plivo');
let fs = require('fs');
let client = new plivo.Client("<auth_id>","<auth_token>");
var callback = {"url":"<URL>", "method":"POST"}
client.campaign.unlinkNumber("<Campaign_ID>",["<Number>"], callback)
.then(function (response) {
console.log(JSON.stringify(response));
}).catch(function (error) {
console.log("err");
console.log(error);
});
Was this code helpful
1
2
3
4
5
6
7
8
curl -i --user auth_id:auth_token \
-H "Content-Type: application/json" \
-d '{
"numbers": ["<Number>"],
"url": "https://<yourdomain>.com/tendlc_status/",
"method": "POST"
}'\
https://api.plivo.com/v1/Account/<Auth_ID>/10dlc/Campaign/<Campaign_ID>/Number/
Was this code helpful
Response
{
"api_id": "2a77676c-4e2f-11ed-bbe4-0242ac110002",
"message": "Request to link 14845197649 to campaign CXXXXX was received and is being processed"
}