Caller Reputation

What: Register your business identity with US carrier networks so outbound calls display your business name instead of being flagged as spam
How: Register your business once on your Business Profile by setting enable_caller_reputation to true, wait for carrier approval, then enable caller_reputation on each number via Update Account Phone Number
Carriers: at&t and t-mobile. verizon is accepted in requests but not supported yet — if you pass it, its leg is reported as NOT_SUPPORTED
Cost: Currently USD 12 per business per month for the AT&T network; the T-Mobile network currently carries no charge. Billed per business (one EIN), not per number. Rates can change and can differ by carrier network
Requires: US-issued EIN (9 digits), business address, website, contact details, and a US local or toll-free number
Limitation: US numbers only, early access beta. Business vetting takes up to 2 business days; numbers attach the same day once the business is approved. It does NOT guarantee calls won’t be flagged — call behavior and volume still matter

Caller Reputation is currently in early access beta and available only for US local and toll-free numbers.

Overview

Caller Reputation lets you register your business identity with major US carrier networks so your outbound calls from US local and toll-free numbers are recognized as legitimate. This reduces the chance your calls are flagged as spam or go unanswered. Registration works in two steps, in this order:

Register your business on your Business Profile. Plivo submits your business details to each carrier network for vetting. Each network approves or rejects your business independently.
Enable numbers under that profile. Once at least one carrier network approves your business, numbers attach quickly — typically within hours.

When Caller Reputation is active on a number, calls from that number display your registered business name on supported devices.

Supported carrier networks

Carrier key	Network	Status
`at&t`	AT&T	Supported
`t-mobile`	T-Mobile	Supported
`verizon`	Verizon	Not supported yet. Accepted in requests — if you pass it, its leg is reported as `NOT_SUPPORTED`, and the request never fails because of it

API responses report each carrier network you registered with in caller_reputation_by_carrier. Omitting caller_reputation_carriers registers all supported networks (at&t and t-mobile); verizon appears only if you explicitly passed it.

Pricing

Item	Detail
Current rates	AT&T network: USD 12 per business per month. T-Mobile network: no charge currently. Rates can change and can differ by carrier network, including for networks added later
Billing unit	Per business (one EIN/profile) — not per number. A business registered with both AT&T and T-Mobile today carries one monthly charge (the AT&T rate)
Multiple numbers	Numbers sharing the same business profile are covered under the same registration. Adding more numbers does not add charges
Multiple businesses	Each distinct business (EIN) on your account bills separately
When you’re charged	Where a network carries a charge, it starts when that network approves your business. Registrations that fail validation or are not approved are not charged
Renewal	Recurring monthly. The charge is for the full month and is not prorated
Cancellation	Deregistering a carrier network (see Deregister your business) stops that network’s future billing. Mid-cycle cancellations are not refunded or prorated. Releasing numbers does not stop billing — the registration, and its charge, stay active until you deregister
Re-enabling	Registering again after you deregister creates a new registration — charges (where a network carries one) start again on approval

Prerequisites

Before setting up Caller Reputation, you need:

A Plivo account
One or more US local or toll-free phone numbers rented through Plivo
Your business details ready:
- EIN (US-issued, 9 digits)
- Business address (including a 2-character US state code)
- Business website
- Contact information (first name, last name, title, business email, and phone in E.164 format)

How to set up Caller Reputation

Step 1: Register your business

Register your business on your Business Profile — the same profile used for 10DLC registration. You can register in either of two ways:

On an existing profile: call the Update Profile API with enable_caller_reputation set to true.
While creating a profile: pass the same fields to the Create Profile API to create the profile and register the business in a single call.

Parameter	Required	Description
`enable_caller_reputation`	Yes	Set to `true` to register your business
`caller_reputation_carriers`	No	Array of carrier networks to register with: `at&t`, `t-mobile`, `verizon`. Omit or pass an empty array to register with all supported networks (`at&t` and `t-mobile`). `verizon` is optional — pass it only if you want its `NOT_SUPPORTED` leg tracked in responses
`url`	No	One callback URL for all Caller Reputation events on this profile — business and number. See Status callbacks
`method`	No	`GET` or `POST` (default: `POST`)

Plivo validates your profile synchronously — EIN (9 digits, US-issued), company name, full address, website, business email, and an authorized contact with an E.164 phone. If anything is missing, the API returns one 400 listing every failure, and nothing is submitted for vetting. If validation passes, Plivo submits your business to each requested carrier network. Each network’s status moves to PENDING and resolves independently to APPROVED or FAILED — one network’s rejection never blocks another.

{
  "api_id": "d8f2869c-6879-11f1-aaed-a238457c948e",
  "profile": {
    "profile_uuid": "8444eccc-5af9-404d-a46f-d2fd31cd74de",
    "company_name": "Acme Software Inc",
    "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"
  }
}

If you pass a carrier value that isn’t recognized — for example, a misspelling like tmobile — the request still succeeds. Plivo does not submit anything for that value and reports it in the response with status FAILED and reason code CARRIER_NOT_RECOGNIZED. Check caller_reputation_by_carrier in every response rather than relying on the HTTP status code alone.

Step 2: Wait for business approval

Business vetting takes up to 2 business days. Check status with the Retrieve Profile API, or receive a callback per carrier network if you set url. A number can attach only to a carrier network whose business status is APPROVED. You don’t need every network approved — one is enough to start enabling numbers on that network.

Step 3: Enable Caller Reputation on your numbers

Call the Update Account Phone Number endpoint:

Parameter	Required	Description
`caller_reputation`	Yes	Set to `enabled`
`profile_uuid`	Yes	Your business profile UUID

The number attaches on every carrier network where your business is APPROVED — attachment typically completes within hours. Networks where your business is still pending, failed, or not registered are not attached; the response tells you why for each one, and you retry those networks by calling the same endpoint again after the business is approved.

{
  "api_id": "f31c07a2-688d-11f1-aaed-a238457c948e",
  "message": "changed",
  "caller_reputation_status": "PENDING",
  "caller_reputation_by_carrier": {
    "at&t":     { "status": "PENDING", "reason_code": null, "reason": null, "updated_at": "2026-08-20T10:02:11Z" },
    "t-mobile": { "status": "NOT_REGISTERED", "reason_code": "BUSINESS_PENDING", "reason": "Business registration on t-mobile is still pending. Retry adding this number after the business is approved.", "updated_at": "2026-08-20T10:02:11Z" },
    "verizon":  { "status": "NOT_SUPPORTED", "reason_code": "CARRIER_NOT_SUPPORTED", "reason": "Verizon is not currently supported for Caller Reputation on Plivo.", "updated_at": null }
  }
}

If no carrier network can attach — the business is pending everywhere, failed everywhere, or was never registered — the request returns a 400 naming the profile’s current per-carrier state. Register or fix the business on the profile first, then retry.

Step 4: Confirm activation

Call the Get Account Phone Number endpoint to check the number’s status. The response returns both a merged caller_reputation_status and a per-carrier breakdown in caller_reputation_by_carrier. Attached networks move from PENDING to ACTIVE when registration completes.

Status values

Business status (on the profile)

Each carrier network moves through these states independently:

Status	Description
`NOT_REGISTERED`	Your business is not registered with this network
`PENDING`	Submitted and being vetted by the carrier network
`APPROVED`	Your business is approved — numbers can attach on this network, and any charge for this network starts
`FAILED`	The registration was rejected. Read `reason_code` and `reason`, fix your profile, and register again
`NOT_SUPPORTED`	Plivo doesn’t offer this carrier network yet (Verizon). Informational only

Number status (on the phone number)

Status	Description
`NOT_REGISTERED`	The number is not attached on this network. `reason_code` and `reason` explain why — for example, the business is still pending on this network
`PENDING`	The number is attached and awaiting confirmation from the carrier network
`ACTIVE`	Registration complete — your business name displays on outbound calls on this network
`FAILED`	The carrier network rejected this number. A number-level failure is specific to the number, not your business vetting
`NOT_SUPPORTED`	Plivo doesn’t offer this carrier network yet (Verizon)

Merged status

caller_reputation_status is a single summary across carrier networks. For the business: APPROVED > PENDING > FAILED > NOT_REGISTERED. For a number: ACTIVE > PENDING > FAILED > NOT_REGISTERED. NOT_SUPPORTED never affects the merged value. Because in-progress and successful states outrank FAILED, a single network’s failure can be hidden in the merged field. Always read caller_reputation_by_carrier to see each network’s real status, not just the merged value.

Reason codes

Every carrier entry that isn’t healthy carries a machine-readable reason_code alongside the human-readable reason, in API responses and callbacks:

Code	Meaning
`CARRIER_NOT_SUPPORTED`	The carrier network is recognized but not offered on Plivo yet (Verizon)
`CARRIER_NOT_RECOGNIZED`	The value you passed in `caller_reputation_carriers` isn’t a recognized carrier network. Nothing was submitted for it
`BUSINESS_PENDING`	Number not attached: your business registration on this network is still pending. Retry after approval
`BUSINESS_FAILED`	Number not attached: your business registration on this network failed. Fix your profile and register again
`BUSINESS_NOT_REGISTERED`	Number not attached: your business isn’t registered on this network. Register it on the profile first
`VENDOR_REJECTED`	The carrier network rejected the registration during vetting. The network’s explanation is in `reason`

Status callbacks

Set url (and optionally method) on your profile to receive one callback stream for all Caller Reputation events — business and number — on that profile. This replaces the earlier per-number callback configuration. Callbacks are form-encoded POST requests (or GET, per your method) signed with V3 signatures — validate X-Plivo-Signature-V3, X-Plivo-Signature-V3-Nonce, and X-Plivo-Signature-Ma-V3 headers.

Event	`Endpoint`	`Status`	When
Business resolved	`caller_reputation_business`	`approved` / `failed`	A carrier network resolves your business registration
Business deregistered	`caller_reputation_business`	`deregistered`	You deregister — fires once per deregistered network
Number resolved	`caller_reputation_number`	`active` / `failed`	A number resolves on a carrier network

Endpoint=caller_reputation_business
Status=failed
ProfileUUID=8444eccc-5af9-404d-a46f-d2fd31cd74de
Carrier=at&t
ReasonCode=VENDOR_REJECTED
Reason=Business name could not be verified.
ResourceCreationTime=2026-08-20 09:14:03.412 +0000 UTC
ResourceUpdatedTime=2026-08-22 16:02:11.006 +0000 UTC

Number events add Number in E.164 format with a leading + (for example, +14155550123). ReasonCode and Reason appear only on failed events. Delivery is at-least-once: respond with a 2xx within 5 seconds, or Plivo retries up to 3 times (after 60, 120, and 240 seconds). Your endpoint must be HTTPS. Deduplicate on the combination of ProfileUUID, Endpoint, Number, Carrier, Status, and ResourceUpdatedTime. As a polling fallback, filter profiles with GET /Profile/?caller_reputation_status=FAILED.

The caller_reputation_callback_url and caller_reputation_callback_method parameters on Update Account Phone Number are deprecated. Plivo accepts them during the migration period and ignores them after. Set url and method on the profile instead.

Fix a failed registration and retry

Business failed on a network: read reason_code and reason from caller_reputation_by_carrier on the profile — the reason persists, so you can read it any time. Fix your profile with the Update Profile API, then call it again with enable_caller_reputation set to true. Plivo retries only the networks that failed — networks that are already approved or pending are not affected, and retrying does not add a charge for a network that’s already registered. Number not attached on a network: the number’s caller_reputation_by_carrier entry tells you why (BUSINESS_PENDING, BUSINESS_FAILED, or BUSINESS_NOT_REGISTERED). Resolve the business state on the profile, then call Update Account Phone Number again with caller_reputation set to enabled. Networks that are already attached are not affected.

Deregister your business

To stop Caller Reputation — and its billing — deregister the business on the profile:

Disable caller_reputation on every number under the profile for the networks you’re deregistering.
Call the Update Profile API with enable_caller_reputation set to false. Pass caller_reputation_carriers to deregister specific networks, or omit it to deregister all.

If numbers are still enrolled on a network you’re deregistering, the API returns a 400 naming the count — Plivo never silently removes branding from numbers with live traffic. Once deregistered, that network’s status returns to NOT_REGISTERED and any charge for that network stops. Registering again later creates a new registration.

Error messages

These problems return an HTTP 400 immediately. Fix them and resubmit.

Error message	Description
`Profile is missing fields required for caller_reputation: ...`	Your profile is missing required business details. The message lists every missing or invalid field — fix them all in one update
`No registered business found for the provided profile_uuid. Enable caller_reputation on the profile first.`	You tried to enable a number under a profile with no registered business
`Business registration for the provided profile_uuid is still pending on all carriers. Retry after the business is approved.`	No carrier network has approved your business yet, so no number can attach
`Disable caller_reputation on all numbers under this profile first. N number(s) are still enrolled.`	You tried to deregister a business that still has enrolled numbers
`This profile has a registered Caller Reputation business. Disable caller_reputation on the profile first.`	You tried to delete a profile with a registered business
`caller_reputation is only supported for US numbers`	The phone number is not a US number. Caller Reputation supports US local and toll-free numbers only
`profile_uuid is required when caller_reputation is enabled`	You set `caller_reputation` to `enabled` on a number but did not provide a `profile_uuid`

FAQ

How much does Caller Reputation cost? Currently USD 12 per business per month for the AT&T network; the T-Mobile network carries no charge today. Billing is per business (one EIN), not per number — a business registered with both networks today pays one monthly charge. Rates can change and can differ by carrier network. See Pricing. When am I charged? Where a network carries a charge, it starts when that network approves your business. Registrations that fail validation or are never approved are not charged. How do I stop being charged? Deregister the business — disable Caller Reputation on the profile’s numbers, then set enable_caller_reputation to false on the profile. Releasing numbers alone does not stop billing. Can I register with only one carrier network? Yes. Pass caller_reputation_carriers with just that network — for example, ["at&t"]. You pay only for the networks you register with. Can I use the same profile for multiple numbers? Yes. You can link a single business profile to as many Plivo numbers as you need. All linked numbers display the same business name and are covered under the same registration. Can I add a number while my business is still pending? The number attaches on any network that has already approved your business. Networks still pending are reported as NOT_REGISTERED with reason code BUSINESS_PENDING — retry those after approval. If no network is approved yet, the request returns a 400. How long does activation take? Business vetting takes up to 2 business days per carrier network. Once a network approves your business, numbers attach the same day — typically within hours. I enrolled numbers before this change. Do I need to do anything? No. Plivo migrates existing registrations to profile-level businesses automatically. Your per-carrier statuses appear on your profile, and your numbers stay enrolled. Does Caller Reputation guarantee my calls won’t be flagged as spam? No. Caller Reputation registers your business identity with supported carrier networks, which helps establish trust. Call behavior, volume patterns, and recipient feedback can still influence spam classification by carriers and device-level apps.

STIR/SHAKEN — Call authentication and attestation
Verified Caller ID — Verify external numbers for use as caller ID
Profile API — Create and manage business profiles
Account Phone Numbers API — Manage your Plivo phone numbers

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

Caller Reputation

Overview

Supported carrier networks

Pricing

Prerequisites

How to set up Caller Reputation

Step 1: Register your business

Step 2: Wait for business approval

Step 3: Enable Caller Reputation on your numbers

Step 4: Confirm activation

Status values

Business status (on the profile)

Number status (on the phone number)

Merged status

Reason codes

Status callbacks

Fix a failed registration and retry

Deregister your business

Error messages

FAQ

​Overview

​Supported carrier networks

​Pricing

​Prerequisites

​How to set up Caller Reputation

​Step 1: Register your business

​Step 2: Wait for business approval

​Step 3: Enable Caller Reputation on your numbers

​Step 4: Confirm activation

​Status values

​Business status (on the profile)

​Number status (on the phone number)

​Merged status

​Reason codes

​Status callbacks

​Fix a failed registration and retry

​Deregister your business

​Error messages

​FAQ

​Related resources

Overview

Supported carrier networks

Pricing

Prerequisites

How to set up Caller Reputation

Step 1: Register your business

Step 2: Wait for business approval

Step 3: Enable Caller Reputation on your numbers

Step 4: Confirm activation

Status values

Business status (on the profile)

Number status (on the phone number)

Merged status

Reason codes

Status callbacks

Fix a failed registration and retry

Deregister your business

Error messages

FAQ

Related resources