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.

API Endpoint

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

The Brand Object

string

Unique identifier for the brand created.

string

A friendly name for the brand.

string

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

string

Legal name of the company.

string

Employer Identification Number associated with a Standard brand.

string

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

string

Type of ownership indicated during brand creation.

string

Company industry.

string

Business website URL.

string

Unique identifier for the profile used to create brand.

string

Indicates status of brand.

integer

Vetting score assigned to brand by TCR.

string

Vetting status of a brand.

array

List of reasons the brand registration was declined. Returned only when registration_status is FAILED. Each entry contains a code and a message.

object

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

object

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

string

ISO 8601 timestamp of when the brand was created. Auto-generated by Plivo; response-only.

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": "OTHER",
      "title": "OTHER"
    },
    "brand_id": "BCDEF1G",
    "brand_type": "STANDARD",
    "company_name": "ABC Inc.",
    "created_at": "2023-03-06T20:59:26.040592Z",
    "ein": "111111111",
    "ein_issuing_country": "US",
    "entity_type": "PRIVATE",
    "profile_uuid": "09849948-656a-41a2-99da-8370251c804b",
    "registration_status": "COMPLETED",
    "vertical": "ENERGY",
    "vetting_score": 80,
    "vetting_status": "ACTIVE",
    "website": "https://www.example.com"
  }
}

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

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.

string

required

A friendly name for the brand.

string

Indicate type of registration. Allowed values: STANDARD. Requires a profile that contains an EIN. Defaults to STANDARD.

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.

string

The fully qualified URL to which status update callbacks for the message should be sent.

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": "US",
      "postal_code": "10001",
      "state": "NY",
      "street": "123"
    },
    "authorized_contact": {
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+12125557777",
      "seniority": "OTHER",
      "title": "OTHER"
    },
    "brand_id": "BVMN1EM",
    "brand_type": "STANDARD",
    "company_name": "ABC Inc.",
    "created_at": "2023-03-06T20:59:26.040592Z",
    "ein": "123456789",
    "ein_issuing_country": "US",
    "entity_type": "PRIVATE",
    "profile_uuid": "dd0b418d-73df-4eb4-a7ab-171b774bf4a9",
    "registration_status": "COMPLETED",
    "vertical": "ENERGY",
    "website": "https://www.example.com"
  }
}

When a brand’s registration is declined (registration_status is FAILED), the response also includes a declined_reasons array:

{
  "api_id": "fdf6eff7-3e3e-4838-9f5b-3f1226fe0ba6",
  "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": "OTHER",
      "title": "OTHER"
    },
    "brand_id": "BEXMPL1",
    "brand_type": "STANDARD",
    "company_name": "ABC Inc.",
    "created_at": "2023-03-06T20:59:26.040592Z",
    "declined_reasons": [
      {
        "code": "1101",
        "message": "The US EIN provided is invalid."
      }
    ],
    "ein": "123456789",
    "ein_issuing_country": "US",
    "entity_type": "PRIVATE",
    "profile_uuid": "dd0b418d-73df-4eb4-a7ab-171b774bf4a9",
    "registration_status": "FAILED",
    "vertical": "RETAIL",
    "website": "https://www.example.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

integer

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

integer

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

string

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

string

Filter by registration type. Allowed values: 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": "TX",
        "street": "#11, Nashville Street"
      },
      "authorized_contact": {
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+12125557777",
        "seniority": "OTHER",
        "title": "OTHER"
      },
      "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