Profile

Create a profile to provide details about your company to Plivo. You can use the profile to create 10DLC brands for messaging customers.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/Profile/

The Profile Object

Attributes

string

A unique identifier for each profile.

string

Indicates whether this is a primary or secondary profile.

string

A unique identifier for the account’s primary profile.

string

A friendly name for the profile.

string

Indicates the nature of your operations and how you use Plivo’s voice and messaging offerings.

string

Indicates ownership of the business.

string

Legal name of the company.

string

Company industry.

string

Employer Identification Number.

string

ISO country code of the country that issued the EIN.

object

Postal address of the company.

object

Details of the authorized contact person at the company.

string

Brand authentication and compliance contact email. Returned for public-facing brands.

string

Customer-facing brand name shown to end users, when it differs from the legal company name.

string

Approximate size of the business, as an employee-count band.

string

Stock symbol of the company.

string

Stock exchange where the company is listed.

string

Alternate business identification number.

string

Alternate business ID type.

string

Business website.

string

Subaccount mapped to the profile.

boolean

Whether this profile’s business is registered for Caller Reputation. true or false.

string

Merged Caller Reputation business status across carrier networks: NOT_REGISTERED, PENDING, APPROVED, or FAILED.

object

Per-carrier business status, keyed by carrier network: at&t and t-mobile, plus verizon when you explicitly requested it (reported as NOT_SUPPORTED). Each entry contains status, reason_code, reason (persists on failures), and updated_at (ISO 8601 UTC). See Status values.

string

Timestamp of the last Caller Reputation status change, in ISO 8601 UTC.

string

ISO 8601 timestamp of when the profile was created. Auto-generated by Plivo; returned only — not a request parameter.

Example Object

{
    "profile": {
        "address": {
            "city": "New York",
            "country": "US",
            "postal_code": "10001",
            "state": "NY",
            "street": "123"
        },
        "alt_business_id": "ABC",
        "alt_business_id_type": "DUNS",
        "authorized_contact": {
            "email": "john@example.com",
            "first_name": "john",
            "last_name": "doe",
            "phone": "12125557777",
            "seniority": "admin",
            "title": "Doe"
        },
        "business_contact_email": "compliance@example.com",
        "company_name": "ABC Inc.12345",
        "created_at": "2026-02-19T08:18:08.713905Z",
        "customer_type": "RESELLER",
        "doing_business_as": "Acme Coffee",
        "ein": "12125552222",
        "ein_issuing_country": "US",
        "entity_type": "PUBLIC",
        "number_of_employees": "BETWEEN_11_AND_50",
        "plivo_subaccount": "SA2025RK4E639VJFZAMM",
        "primary_profile": "c780f9d0-e3c9-4d13-87f7-b898654569b0",
        "profile_alias": "john_doe",
        "profile_type": "SECONDARY",
        "profile_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
        "stock_exchange": "NYSE",
        "stock_symbol": "HIBYE",
        "vertical": "ENTERTAINMENT",
        "website": "hibye.com",
        "enable_caller_reputation": true,
        "caller_reputation_status": "APPROVED",
        "caller_reputation_by_carrier": {
            "at&t":     { "status": "APPROVED", "reason_code": null, "reason": null, "updated_at": "2026-08-21T11:05:00Z" },
            "t-mobile": { "status": "PENDING", "reason_code": null, "reason": null, "updated_at": "2026-08-20T09:14:03Z" },
            "verizon":  { "status": "NOT_SUPPORTED", "reason_code": "CARRIER_NOT_SUPPORTED", "reason": "Verizon is not currently supported for Caller Reputation on Plivo.", "updated_at": null }
        },
        "caller_reputation_updated_at": "2026-08-21T11:05:00Z"
    }
}

Create a Profile

Create a business profile for your end customers.

POST https://api.plivo.com/v1/Account/{auth_id}/Profile/

Arguments

string

required

A friendly name for your profile.

string

required

Indicates the nature of your operations. Allowed values: DIRECT, RESELLER. Select RESELLER if your business provides communication services such as messaging and voice calling to other businesses.

string

required

Indicates ownership of the company. Allowed values: PRIVATE, PUBLIC, NON_PROFIT, GOVERNMENT, INDIVIDUAL.

string

required

Legal name of the company.

string

required

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.

object

required

Valid postal address of the company. Object fields: street, city, state (valid state code, e.g., TX for Texas), postal_code (ZIP code), country (ISO alpha-2 country code, e.g., US).

object

required

Authorized contact person at the company. Object fields: first_name, last_name, email, title (salutation), seniority (allowed values: DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER), phone (E.164 format).

string

Brand authentication and compliance contact email. Required for public-facing brands. Must be on the business’s own corporate domain — not a public domain (gmail.com, yahoo.com, outlook.com, hotmail.com, etc.) and not a distribution list or role alias (info@, support@, sales@, etc.). The mailbox should belong to a real, reachable person at the business.

string

Customer-facing brand name shown to end users, when it differs from the legal company_name. For example, a business legally registered as “Acme Holdings LLC” but operating publicly as “Acme Coffee” would set this to “Acme Coffee”. Leave empty if the legal and public names are identical.

string

Approximate size of the business, expressed as an employee-count band. Allowed values: BETWEEN_1_AND_10, BETWEEN_11_AND_50, BETWEEN_51_AND_200, BETWEEN_201_AND_500, BETWEEN_501_AND_2000, BETWEEN_2001_AND_10000, MORE_THAN_10001.

string

Employer Identification Number. Plivo strongly recommends providing your EIN if your company is registered to unlock premium features like high throughput.

string

The ISO country code of the country that issued the EIN.

string

Stock symbol of the company.

string

Stock exchange where your company is listed. Allowed values: NASDAQ, NYSE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JPX, JSE, KRX, LON, NSE, OMX, SEHK, SGX, SSE, STO, SWX, SZSE, TSX, TWSE, VSE, OTHER.

string

Alternate business identification number.

string

Alternate business ID type. Allowed values: DUNS, LEI, GIIN, NONE.

string

Website of the business.

string

Subaccount mapped to the profile.

boolean

Set to true to register this profile’s business with US carrier networks for Caller Reputation as part of profile creation — one call creates the profile and registers the business. Requires EIN, address, website, business email, and an authorized contact; if any are missing, the request returns one 400 listing every missing field.

array

Carrier networks to register the business with. Values: at&t, t-mobile, verizon. Omit or pass an empty array for all supported networks (at&t and t-mobile). verizon is optional and not supported yet — pass it only if you want its leg tracked; it’s reported as NOT_SUPPORTED and never fails the request.

string

One callback URL for all Caller Reputation events on this profile. See Status callbacks.

string

HTTP method for the Caller Reputation callback. Allowed values: GET, POST. Defaults to POST.

If you specify entity_type=INDIVIDUAL, you can skip fields like ein, ein_issuing_country, stock_symbol, stock_exchange, alt_business_id, and alt_business_id_type.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.profile.create(
    profile_alias="profile name sample",
    customer_type="DIRECT",
    entity_type="PRIVATE",
    company_name="ABC Inc.",
    ein="123456789",
    ein_issuing_country="US",
    stock_symbol="ABC",
    stock_exchange="NSE",
    website="www.example.com",
    vertical="REAL_ESTATE",
    business_contact_email="john@example.com",
    doing_business_as="Acme Coffee",
    alt_business_id="",
    alt_business_id_type="NONE",
    address={
        "street": "123",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    },
    authorized_contact={
        "first_name": "john",
        "last_name": "doe",
        "phone": "12025551234",
        "email": "john@example.com",
        "title": "Mr",
        "seniority": "admin"
    },
)
print(response)

const plivo = require('plivo');

const client = new plivo.Client("<auth_id>", "<auth_token>");

const address = {
    street: "660 Broadway",
    city: "New York",
    state: "NY",
    postal_code: "10001",
    country: "US"
};

const authorizedContact = {
    first_name: "John",
    last_name: "Doe",
    email: "john@example.com",
    title: "manager",
    seniority: "admin",
    phone: "+12125551234"
};

client.profile.create(
    "my_profile",
    "",
    "DIRECT",
    "PRIVATE",
    "ABC Inc",
    "111111111",
    "PROFESSIONAL",
    "US",
    "ABC",
    "NASDAQ",
    "NONE",
    "example.com",
    address,
    authorizedContact,
    "john@example.com",
    "Acme Coffee"
).then(console.log).catch(console.error);

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
        "profile_alias": "john_new",
        "customer_type": "DIRECT",
        "entity_type": "PRIVATE",
        "company_name": "ABC Inc.",
        "vertical": "ENTERTAINMENT",
        "ein": "122321231",
        "ein_issuing_country": "US",
        "address": {
            "street": "660 Broadway",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "US"
        },
        "stock_symbol": "ABC",
        "stock_exchange": "NYSE",
        "alt_business_id_type": "DUNS",
        "alt_business_id": "ABC",
        "website": "example.com",
        "business_contact_email": "john@example.com",
        "doing_business_as": "Acme Coffee",
        "number_of_employees": "BETWEEN_1_AND_10",
        "authorized_contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "title": "manager",
            "seniority": "admin",
            "phone": "12125551234"
        }
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Profile/

Response

{
    "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
    "message": "Profile created successfully.",
    "profile_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}

Retrieve a Profile

Fetch details about a specific profile associated with your account.

GET https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Arguments

string

required

The unique identifier of the profile to retrieve.

import plivo

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

const plivo = require('plivo');

const client = new plivo.Client("<auth_id>", "<auth_token>");
client.profile.get("<profile_uuid>")
    .then(console.log)
    .catch(console.error);

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Response

{
    "api_id": "752e99d0-baf3-11ec-ac74-0242ac110002",
    "profile": {
        "address": {
            "city": "New York",
            "country": "US",
            "postal_code": "10001",
            "state": "NY",
            "street": "123"
        },
        "alt_business_id": "ABC",
        "alt_business_id_type": "DUNS",
        "authorized_contact": {
            "email": "john@example.com",
            "first_name": "john",
            "last_name": "doe",
            "phone": "12125557777",
            "seniority": "admin",
            "title": "Doe"
        },
        "business_contact_email": "compliance@example.com",
        "company_name": "ABC Inc.12345",
        "created_at": "2026-02-19T08:18:08.713905Z",
        "customer_type": "RESELLER",
        "doing_business_as": "Acme Coffee",
        "ein": "12125552222",
        "ein_issuing_country": "US",
        "entity_type": "PUBLIC",
        "number_of_employees": "BETWEEN_11_AND_50",
        "plivo_subaccount": "SAXXXXX",
        "primary_profile": "c780f9d0-e3c9-4d13-87f7-b898654569b0",
        "profile_alias": "john_doe",
        "profile_type": "SECONDARY",
        "profile_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
        "stock_exchange": "NYSE",
        "stock_symbol": "HIBYE",
        "vertical": "ENTERTAINMENT",
        "website": "hibye.com"
    }
}

List All Profiles

Fetch all profiles created by your account.

GET https://api.plivo.com/v1/Account/{auth_id}/Profile/

Arguments

integer

Number of results per page. Maximum is 20. Default: 20.

integer

Number of results to skip. Default: 0.

string

Filter by entity type. Allowed values: PRIVATE, PUBLIC, NON_PROFIT, GOVERNMENT, INDIVIDUAL.

string

Filter by profile type. Allowed values: PRIMARY, SECONDARY.

string

Filter by the profile’s merged Caller Reputation business status. Allowed values: NOT_REGISTERED, PENDING, APPROVED, FAILED.

string

Filter by vertical. 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.

import plivo

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

const plivo = require('plivo');

const client = new plivo.Client("<auth_id>", "<auth_token>");
client.profile.list({ limit: 10, offset: 0 })
    .then(console.log)
    .catch(console.error);

curl -i --user auth_id:auth_token \
    "https://api.plivo.com/v1/Account/{auth_id}/Profile/?limit=10&offset=0"

Response

{
    "api_id": "837b1e38-68a1-4fd6-a532-ea4jj888uuhh",
    "meta": {
        "limit": 10,
        "offset": 0,
        "next": "/v1/Account/<AUTH_ID>/Profile/?limit=10&offset=10",
        "previous": null
    },
    "profiles": [
        {
            "profile_uuid": "7a799f1a-5f44-43fb-ac82-999uujnnhhy",
            "profile_alias": "sample name",
            "profile_type": "SECONDARY",
            "primary_profile": "a7fe9aa3-dbca-401e-80a2-f88dudhdbhd",
            "customer_type": "DIRECT",
            "entity_type": "PRIVATE_PROFIT",
            "company_name": "Name of Company",
            "ein": "111111111",
            "ein_issuing_country": "US",
            "address": {
                "street": "660 Broadway",
                "city": "New York",
                "state": "NY",
                "postal_code": "10001",
                "country": "US"
            },
            "website": "www.example.com",
            "vertical": "COMMUNICATION",
            "plivo_subaccount": "SAXXXXX",
            "stock_symbol": "NSQ",
            "stock_exchange": "NASDAQ",
            "alt_business_id": "ABC",
            "alt_business_id_type": "DUNS",
            "authorized_contact": {
                "first_name": "First Name",
                "last_name": "Last Name",
                "phone": "919033998877",
                "email": "contact@example.com",
                "title": "Manager",
                "seniority": "Mr."
            },
            "business_contact_email": "compliance@example.com",
            "doing_business_as": "Acme Coffee",
            "number_of_employees": "BETWEEN_11_AND_50",
            "created_at": "2023-10-17T20:57:54.164054Z"
        }
    ]
}

Update a Profile

Update certain information in a profile.

POST https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Arguments

string

required

The unique identifier of the profile to update.

string

Ownership of the company. Allowed values: PRIVATE, PUBLIC, NON_PROFIT, GOVERNMENT, INDIVIDUAL.

string

Legal name of the company.

string

Company 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.

object

Postal address of the company.

object

Details of the authorized contact person at the company.

string

Brand authentication and compliance contact email. Must be on the business’s own corporate domain — not a public domain (gmail.com, yahoo.com, outlook.com, hotmail.com, etc.) and not a distribution list or role alias (info@, support@, sales@, etc.).

string

Customer-facing brand name shown to end users, when it differs from the legal company_name. Leave empty if the legal and public names are identical.

string

Business website.

string

Subaccount mapped to the profile.

boolean

Set to true to register this profile’s business with US carrier networks for Caller Reputation, or false to deregister. Omit for no change.

array

Carrier networks to register (or deregister) the business with. Values: at&t, t-mobile, verizon. Omit or pass an empty array for all supported networks (at&t and t-mobile). verizon is optional and not supported yet — pass it only if you want its leg tracked; it’s reported as NOT_SUPPORTED and never fails the request. Unrecognized values are not submitted and are reported as FAILED with reason code CARRIER_NOT_RECOGNIZED.

string

One callback URL for all Caller Reputation events on this profile — business and number. See Status callbacks.

string

HTTP method for the Caller Reputation callback. Allowed values: GET, POST. Defaults to POST.

Caller Reputation Behavior

Setting enable_caller_reputation to true validates the profile’s business details synchronously — EIN (9 digits, US-issued), company name, full address, website, business email, and an authorized contact with an E.164 phone — and returns one 400 listing every failure if anything is missing. If validation passes, Plivo submits the business to each requested carrier network; each network resolves independently to APPROVED or FAILED. Repeating the call is a no-op for networks already registered, adds newly listed ones, and retries the failed ones. Setting enable_caller_reputation to false deregisters the networks in caller_reputation_carriers (all when omitted) and stops each network’s billing. The request returns a 400 if numbers are still enrolled on a network you’re deregistering — disable Caller Reputation on those numbers first. The response includes the profile’s caller_reputation_status, caller_reputation_by_carrier, and caller_reputation_updated_at fields — see The Profile Object and Caller Reputation for the full status model.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
params = {"company_name": "New Company Name", "website": "www.example.com", "business_contact_email": "compliance@example.com", "doing_business_as": "Acme Coffee"}
response = client.profile.update("<profile_uuid>", params)
print(response)

const plivo = require('plivo');

const client = new plivo.Client("<auth_id>", "<auth_token>");
const params = { company_name: "New Company Name", business_contact_email: "compliance@example.com", doing_business_as: "Acme Coffee" };
client.profile.update("<profile_uuid>", params)
    .then(console.log)
    .catch(console.error);

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
        "vertical": "ENTERTAINMENT",
        "company_name": "New Company Name",
        "business_contact_email": "compliance@example.com",
        "doing_business_as": "Acme Coffee",
        "number_of_employees": "BETWEEN_11_AND_50"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Response

{
    "api_id": "752e99d0-baf3-11ec-ac74-0242ac110002",
    "profile": {
        "address": {
            "city": "New York",
            "country": "US",
            "postal_code": "10001",
            "state": "NY",
            "street": "123"
        },
        "alt_business_id": "ABC",
        "alt_business_id_type": "DUNS",
        "authorized_contact": {
            "email": "john@example.com",
            "first_name": "john",
            "last_name": "doe",
            "phone": "12125557778",
            "seniority": "admin",
            "title": "Doe"
        },
        "business_contact_email": "compliance@example.com",
        "company_name": "New Company Name",
        "created_at": "2026-02-19T08:18:08.713905Z",
        "customer_type": "RESELLER",
        "doing_business_as": "Acme Coffee",
        "ein": "12125552222",
        "ein_issuing_country": "US",
        "entity_type": "PUBLIC",
        "number_of_employees": "BETWEEN_11_AND_50",
        "plivo_subaccount": "SA2025RK4E639VJFZAMM",
        "primary_profile": "c780f9d0-e3c9-4d13-87f7-b898654569b0",
        "profile_alias": "john_doe",
        "profile_type": "SECONDARY",
        "profile_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
        "stock_exchange": "NYSE",
        "stock_symbol": "HIBYE",
        "vertical": "ENTERTAINMENT",
        "website": "hibye.com",
        "enable_caller_reputation": true,
        "caller_reputation_status": "PENDING",
        "caller_reputation_by_carrier": {
            "at&t":     { "status": "PENDING", "reason_code": null, "reason": null, "updated_at": "2026-08-20T09:14:03Z" },
            "t-mobile": { "status": "PENDING", "reason_code": null, "reason": null, "updated_at": "2026-08-20T09:14:03Z" },
            "verizon":  { "status": "NOT_SUPPORTED", "reason_code": "CARRIER_NOT_SUPPORTED", "reason": "Verizon is not currently supported for Caller Reputation on Plivo.", "updated_at": null }
        },
        "caller_reputation_updated_at": "2026-08-20T09:14:03Z"
    }
}

Delete a Profile

Delete a specific profile from your account. This action is irreversible. You cannot delete the primary profile of an account.

You cannot delete a profile with a registered Caller Reputation business. The request returns a 400: "This profile has a registered Caller Reputation business. Disable caller_reputation on the profile first." Deregister the business, then delete the profile.

DELETE https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Arguments

string

required

The unique identifier of the profile to delete.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.profile.delete(profile_uuid="<profile_uuid>")
print(response)

const plivo = require('plivo');

const client = new plivo.Client("<auth_id>", "<auth_token>");
client.profile.delete("<profile_uuid>")
    .then(console.log)
    .catch(console.error);

curl -X DELETE -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/Profile/{profile_uuid}/

Response

{
    "api_id": "aaf7717a-c149-11ec-a932-0242ac110003",
    "message": "Profile deleted successfully."
}

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

API Endpoint

The Profile Object

Attributes

Example Object

Create a Profile

Arguments

Retrieve a Profile

Arguments

List All Profiles

Arguments

Update a Profile

Arguments

Caller Reputation Behavior

Delete a Profile

Arguments