Brand

Register brands for your or your customers’ businesses to enable 10DLC messaging campaigns. A brand represents the business entity that will be sending messages.

Starter brand registrations are currently paused. See 10DLC Starter Paused for more information.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

The Brand Object

brand_id

string

Unique identifier for the brand created.

brand_alias

string

A friendly name for the brand.

brand_type

string

Type of registration indicated during brand creation. Values: STANDARD, STARTER.

company_name

string

Legal name of the company.

ein

string

Employer Identification Number associated with a Standard brand.

ein_issuing_country

string

ISO alpha-2 code for the country that issued the EIN.

entity_type

string

Type of ownership indicated during brand creation.

vertical

string

Company industry.

profile_uuid

string

Unique identifier for the profile used to create brand.

registration_status

string

Indicates status of brand.

vetting_score

integer

Vetting score assigned to brand by TCR.

vetting_status

string

Vetting status of a brand.

address

object

Postal address indicated during brand creation. Contains street, city, state, postal_code, and country.

authorized_contact

object

Authorized contact information indicated during brand creation. Contains first_name, last_name, email, phone, title, and seniority.

Example Object

{
  "brand": {
    "address": {
      "city": "New York",
      "country": "US",
      "postal_code": "10001",
      "state": "NY",
      "street": "123"
    },
    "authorized_contact": {
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+12125557777",
      "seniority": "admin",
      "title": "Doe"
    },
    "brand_id": "BCDEF1G",
    "brand_type": "STANDARD",
    "company_name": "ABC Inc.",
    "ein": "111111111",
    "ein_issuing_country": "US",
    "entity_type": "PRIVATE_PROFIT",
    "profile_uuid": "09849948-656a-41a2-99da-8370251c804b",
    "registration_status": "COMPLETED",
    "vertical": "ENERGY",
    "vetting_score": 80,
    "vetting_status": "ACTIVE"
  }
}

Register a Standard Brand

This API lets you register a standard brand using a preexisting profile.

POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

Arguments

profile_uuid

string

required

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_alias

string

required

A friendly name for the brand.

brand_type

string

Indicate type of registration. Allowed values: STANDARD, STARTER. STANDARD not allowed for profiles not containing an EIN. Defaults to STARTER.

secondary_vetting

boolean

Allowed values: true, false. Only applicable for STANDARD registration. Defaults to true. Plivo strongly recommends opting for vetting to get the highest throughput for your brands and campaigns.

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. Defaults to POST.

Returns

Returns api_id for the request, unique brand_id, and success message.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.brand.create(
    brand_alias="brand name sample",
    brand_type="STANDARD",
    profile_uuid="7bc67ed6-dc92-4958-9acc-e4fdb09bd923",
    secondary_vetting=False,
    url="https://example.com/test",
    method="POST",
)
print(response)

let plivo = require('plivo');

let client = new plivo.Client("<auth_id>", "<auth_token>");
var callback = {"url":"https://<yourdomain>.com/tendlc_status/", "method":"POST"}

client.brand.create("govt", "<profile_uuid>", "STANDARD", true, callback)
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log("err");
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
            "brand_alias": "gov234t",
            "profile_uuid": "d61eaaaa-18b1-4473-8810-0b9d80573aa9",
            "brand_type": "STANDARD",
            "secondary_vetting": true,
            "url": "https://<yourdomain>.com/tendlc_status/",
            "method": "POST"
        }' \
        https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

Response

{
  "api_id": "5df3fffa-64ab-11ed-b94d-0242ac110002",
  "brand_id": "BB9TT3V",
  "message": "Request to create brand was received and is being processed."
}

Retrieve a Brand

This API lets you fetch details about a specific brand associated with your account.

GET https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{brand_id}/

Arguments

No arguments need to be passed.

Returns

Returns api_id and the brand object identified by the brand_id specified in the request URL.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.brand.get("<brand_id>")
print(response)

let plivo = require('plivo');

let client = new plivo.Client("<auth_id>", "<auth_token>");
client.brand.get("<brand_id>")
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log("err");
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{brand_id}/

Response

{
  "api_id": "0215c238-1701-11ed-9d48-0242ac110003",
  "brand": {
    "address": {
      "city": "New York",
      "country": "IN",
      "postal_code": "10001",
      "state": "NY",
      "street": "123"
    },
    "authorized_contact": {
      "email": "test@plivo.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "1890342302",
      "seniority": "admin",
      "title": "Doe"
    },
    "brand_id": "BVMN1EM",
    "brand_type": "STARTER",
    "ein_issuing_country": "IN",
    "entity_type": "PRIVATE",
    "profile_uuid": "dd0b418d-73df-4eb4-a7ab-171b774bf4a9",
    "registration_status": "COMPLETED",
    "vertical": "ENERGY",
    "website": "www.google.com"
  }
}

List All Brands

This API lets you fetch all the brands associated with an account.

GET https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

Arguments

limit

integer

Denotes the number of results per page. The maximum number of results that can be fetched is 20. Defaults to 20.

offset

integer

Denotes the number of value items by which the results should be offset. Defaults to 0.

registration_status

string

Filter by registration_status. Allowed values: FAILED, PROCESSING, COMPLETED.

type

string

Filter by registration type. Allowed values: STARTER, STANDARD.

Returns

Returns api_id and a dictionary with an objects property that contains up to 20 brands. Each tuple in the list is a separate Brand object.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.brand.list(limit=1, offset=0)
print(response)

let plivo = require('plivo');

let client = new plivo.Client("<auth_id>", "<auth_token>");
client.brand.list()
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log("err");
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/

Response

{
  "api_id": "553379bc-6c9a-4f5d-8e8f-e0999euejene8",
  "meta": {
    "limit": 1,
    "offset": 0,
    "next": "/v1/Account/<AUTH_ID>/10dlc/Brand/?limit=1&offset=1",
    "previous": null,
    "total_count": 45
  },
  "brands": [
    {
      "brand_alias": "sample name",
      "brand_id": "BXXXXX",
      "brand_type": "STANDARD",
      "company_name": "sample company",
      "ein": "123456789",
      "ein_issuing_country": "US",
      "entity_type": "PUBLIC",
      "profile_uuid": "7b8ff904-a1d2-46b2-888d-34d4df4cf95a",
      "registration_status": "COMPLETED",
      "vertical": "COMMUNICATION",
      "vetting_score": 80,
      "vetting_status": "ACTIVE",
      "website": "www.samplewebsite.com",
      "Address": {
        "city": "Dallas",
        "country": "US",
        "postal_code": "10001",
        "state": "Texas",
        "street": "#11, Nashville Street"
      },
      "Authorized_contact": {
        "email": "xxxx@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "14845355113",
        "seniority": "Admin",
        "title": "Mr"
      },
      "created_at": "2023-03-06T20:59:26.040592Z"
    }
  ]
}

Delete a Brand

Deletes a particular 10DLC brand from your account. This action is irreversible and is only allowed for brands with no associated active campaigns.

DELETE https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{brand_id}/

Arguments

No arguments need to be passed.

Returns

Returns api_id, brand_id, and a confirmation (or error message).

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.brand.delete(brand_id='<brand_id>')
print(response)

let plivo = require('plivo');

let client = new plivo.Client("<auth_id>", "<auth_token>");
client.brand.deleteBrand("<brand_id>").then(function(response) {
    console.log(JSON.stringify(response));
}).catch(function(error) {
    console.log("err");
    console.log(error);
});

curl --location --request DELETE 'https://api.plivo.com/v1/Account/<auth_id>/10dlc/Brand/<brand_id>/' \
    --header 'Authorization: Basic XXXX=='

Response

{
  "api_id": "785ed2dc-7493-11ed-97ac-0242ac110003",
  "brand_id": "BCHVILW",
  "message": "Brand Deactivated"
}

Get Brand Use Cases

Fetches details about what kind of campaigns are supported under a particular brand ID.

GET https://api.plivo.com/v1/Account/{auth_id}/10dlc/Brand/{brand_id}/usecases/

Arguments

No arguments need to be passed.

Returns

Returns api_id, brand_id, and a list containing all the types of campaign types allowed for the brand.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.brand.get_usecases(brand_id='<brand_id>')
print(response)

let plivo = require('plivo');

let client = new plivo.Client("<auth_id>", "<auth_token>");
client.brand.get_usecases("<brand_id>")
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log("err");
        console.log(error);
    });

curl --location --request GET 'https://api.plivo.com/v1/Account/<auth_id>/10dlc/Brand/<brand_id>/usecases/' \
    --header 'Authorization: Basic XXXX=='

Response

{
  "api_id": "0db62668-5f2d-11ed-bee0-0242ac110002",
  "brand_id": "BJZN6KW",
  "use_cases": [
    {
      "code": "2FA",
      "details": "Any two-factor authentication with passcodes used to unlock accounts",
      "name": "Two-Factor Authentication"
    },
    {
      "code": "ACCOUNT_NOTIFICATION",
      "details": "Notification sent to account holders about changes in accounts",
      "name": "Account Notification"
    },
    {
      "code": "CUSTOMER_CARE",
      "details": "Customer care interactions by the support and other customer-facing teams",
      "name": "Customer Care"
    },
    {
      "code": "DELIVERY_NOTIFICATION",
      "details": "Updates about the delivery of products and services",
      "name": "Delivery Notification"
    },
    {
      "code": "FRAUD_ALERT",
      "details": "Notifications of suspicious behavior identified the business",
      "name": "Fraud Alert"
    },
    {
      "code": "HIGHER_EDUCATION",
      "details": "Messages sent by colleges, universities, and other educational institutions",
      "name": "Higher Education"
    },
    {
      "code": "LOW_VOLUME",
      "details": "A combination of two to five standard usage cases - for low throughput requirements",
      "name": "Low Volume"
    },
    {
      "code": "MARKETING",
      "details": "Communications related to time-bound events and sales",
      "name": "Marketing"
    },
    {
      "code": "MIXED",
      "details": "A combination of two to five standard usage cases",
      "name": "Mixed"
    },
    {
      "code": "POLLING_VOTING",
      "details": "Surveys, polling, and voting campaigns used for non-political purposes",
      "name": "Polling Voting"
    },
    {
      "code": "PUBLIC_SERVICE_ANNOUNCEMENT",
      "details": "Messages aimed at creating awareness about important topics",
      "name": "Public Service Announcement"
    },
    {
      "code": "SECURITY_ALERT",
      "details": "Notifications that alert users about a potential breach of systems",
      "name": "Security Alert"
    }
  ]
}

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

API Endpoint

The Brand Object

Example Object

Register a Standard Brand

Arguments

Returns

Response

Retrieve a Brand

Arguments

Returns

Response

List All Brands

Arguments

Returns

Response

Delete a Brand

Arguments

Returns

Response

Get Brand Use Cases

Arguments

Returns

Response

​API Endpoint

​The Brand Object

​Example Object

​Register a Standard Brand

​Arguments

​Returns

​Response

​Retrieve a Brand

​Arguments

​Returns

​Response

​List All Brands

​Arguments

​Returns

​Response

​Delete a Brand

​Arguments

​Returns

​Response

​Get Brand Use Cases

​Arguments

​Returns

​Response

API Endpoint

The Brand Object

Example Object

Register a Standard Brand

Arguments

Returns

Response

Retrieve a Brand

Arguments

Returns

Response

List All Brands

Arguments

Returns

Response

Delete a Brand

Arguments

Returns

Response

Get Brand Use Cases

Arguments

Returns

Response