Caller Reputation

What: Register your business identity with US carriers (AT&T and T-Mobile) so outbound calls display your business name instead of being flagged as spam
How: Create a Business Profile with your EIN, then enable caller_reputation on each number via Update Account Phone Number
Cost: USD 12 per registered business per month — charged per business (one EIN), not per number
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, activation takes up to 2 business days. 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 carriers 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. Plivo registers each number with two carrier networks:

AT&T
T-Mobile

You enroll once. Plivo submits your registration to both networks and reports the result for each. When Caller Reputation is active on a number, calls from that number display your registered business name on supported devices.

Pricing

Item	Detail
Price	USD 12 per registered business per month
Billing unit	Per business (one EIN/profile) — not per number
Multiple numbers	Numbers sharing the same business profile are covered under the same USD 12. Adding more numbers to an approved business does not add charges
Multiple businesses	Each distinct business (EIN) on your account bills separately. Two businesses cost 2 × USD 12
When you’re charged	When your business registration is approved. 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	Disabling or releasing the last number of a business stops future billing. Mid-cycle cancellations are not refunded or prorated
Re-enabling	Re-enabling a number for a business you previously removed creates a new registration and a new monthly charge

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: Create a Business Profile

Create a business profile using the Profile API. This is the same profile used for 10DLC registration — if you already have one, you can reuse it. Your profile must include your business name, EIN, address, website, and contact details. You can also set number_of_employees to one of:

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

If you don’t set number_of_employees, Plivo uses a default of BETWEEN_51_AND_200 for AT&T registration. Set it to reflect your actual business size for the most accurate registration. You can add it later with the Update Profile API and re-enable the number.

Step 2: Enable Caller Reputation on a phone number

Call the Update Account Phone Number endpoint with the following parameters:

Parameter	Required	Description
`caller_reputation`	Yes	Set to `enabled`
`profile_uuid`	Yes	Your business profile UUID
`caller_reputation_callback_url`	No	URL that receives status update notifications
`caller_reputation_callback_method`	No	`GET` or `POST` (default: `POST`)

This submits your registration to both carrier networks and returns an HTTP 202 with the initial per-carrier status.

If a different business profile already owns this number, Plivo automatically reassigns it to the new business. The number status shows PENDING while the reassignment is processed.

Step 3: Confirm activation

Call the Get Account Phone Number endpoint to check status. The response returns both a merged caller_reputation_status and a per-carrier breakdown in caller_reputation_by_carrier. If you provided a caller_reputation_callback_url, Plivo also notifies you when each carrier reaches a final status. See Status callbacks.

Status values

Each carrier moves through these states independently:

Status	Description
`PENDING`	Registration submitted and being processed by carrier partners
`ACTIVE`	Registration complete — your business name displays on outbound calls for that carrier
`FAILED`	Registration was rejected. Read the `reason` and retry — see Fix a failed registration and retry
`NOT_ENROLLED`	The number is not enrolled for that carrier

Merged status

caller_reputation_status is a single summary across both carriers, resolved in this order:

If any carrier is ACTIVE → ACTIVE
Else if any carrier is PENDING → PENDING
Else if any carrier is FAILED → FAILED
Else → NOT_ENROLLED

Because PENDING and ACTIVE outrank FAILED, a single carrier’s failure can be hidden in the merged field. Always read caller_reputation_by_carrier to see each carrier’s real status, not just the merged value.

Activation can take up to 2 business days after you enable a number. Only one profile can be associated per EIN.

API responses

The Update Account Phone Number and Get Account Phone Number endpoints return these Caller Reputation fields:

Field	Type	Description
`caller_reputation`	string	`enabled` or `disabled`
`caller_reputation_status`	string	Merged status across all carriers
`caller_reputation_by_carrier`	object	Per-carrier breakdown, keyed by `att` and `tmobile`

Each entry in caller_reputation_by_carrier contains:

Field	Description
`status`	That carrier’s status — `PENDING`, `ACTIVE`, `FAILED`, or `NOT_ENROLLED`
`reason`	An actionable message explaining a validation failure. Returned only in the enable response (Update Account Phone Number), not in the Get Account Phone Number response
`updated_at`	RFC 3339 timestamp of the last status change. Returned on the Get Account Phone Number response

reason is returned only in the synchronous enable response. The Get Account Phone Number response and status callbacks report each carrier’s status but not a reason. Capture the reason from the enable response when you enroll a number. If a carrier later shows FAILED without a reason, review your profile against the requirements in Error messages.

Enable response — both carriers accepted

{
  "api_id": "d8f2869c-6879-11f1-aaed-a238457c948e",
  "message": "changed",
  "caller_reputation_status": "PENDING",
  "caller_reputation_by_carrier": {
    "tmobile": { "status": "PENDING" },
    "att": { "status": "PENDING" }
  }
}

Enable response — one carrier needs a fix

In this example T-Mobile is processing, but AT&T failed validation because the profile is missing a website. The request still succeeds with 202 — one carrier’s failure does not block the other.

{
  "api_id": "1255cb66-688d-11f1-aaed-a238457c948e",
  "message": "changed",
  "caller_reputation_status": "PENDING",
  "caller_reputation_by_carrier": {
    "tmobile": { "status": "PENDING" },
    "att": {
      "status": "FAILED",
      "reason": "The profile must have a website set for AT&T caller reputation. Update the profile to add a website, then re-enable the number."
    }
  }
}

Get number status — both carriers active

{
  "caller_reputation": "enabled",
  "caller_reputation_status": "ACTIVE",
  "caller_reputation_by_carrier": {
    "tmobile": { "status": "ACTIVE", "updated_at": "2026-06-17T10:32:00Z" },
    "att": { "status": "ACTIVE", "updated_at": "2026-06-17T11:05:00Z" }
  },
  "profile_uuid": "8444eccc-5af9-404d-a46f-d2fd31cd74de"
}

Status callbacks

If you set caller_reputation_callback_url, Plivo sends a callback when a carrier reaches a final status (ACTIVE or FAILED). Callbacks are not sent for PENDING.

One callback per carrier. A number enrolled on both carriers receives two callbacks — one for AT&T and one for T-Mobile — which may arrive at different times and with different statuses.
caller_reputation_status in the callback is that single carrier’s status, not the merged value.
Delivery is best-effort. Respond with any 2xx status to acknowledge.

Callback payload

Plivo sends the payload using the method set in caller_reputation_callback_method (POST by default):

{
  "number": "14155550123",
  "carrier": "att",
  "caller_reputation_status": "ACTIVE",
  "auth_id": "<your_auth_id>",
  "profile_uuid": "8444eccc-5af9-404d-a46f-d2fd31cd74de"
}

Field	Description
`number`	The enrolled phone number, without a leading `+` (for example, `14155550123`)
`carrier`	`att` or `tmobile`
`caller_reputation_status`	That carrier’s final status — `ACTIVE` or `FAILED`
`auth_id`	Your account auth ID
`profile_uuid`	The business profile used for registration

Fix a failed registration and retry

When a carrier shows FAILED, registration retries through the same Update Account Phone Number call you used to enable it. There is no separate retry endpoint.

Find the cause. The enable response from Update Account Phone Number includes a reason for any carrier that fails validation — note it. A later status check from Get Account Phone Number shows the carrier as FAILED but does not repeat the reason, so if you no longer have it, review your profile against Error messages.
Fix your profile. Correct the issue on your Business Profile with the Update Profile API — for example, set number_of_employees or correct the EIN.
Re-enable the number. Call Update Account Phone Number again with caller_reputation set to enabled and the same profile_uuid. Plivo retries registration for the carriers that previously failed.

The failed carrier returns to PENDING, then moves to ACTIVE once registration completes. A carrier that is already ACTIVE is not affected by a retry.

Retrying does not add a charge for a business that is already registered. However, if you previously released the last number of a business — which cancels its registration — re-enabling creates a new registration and a new monthly charge. See Pricing.

Error messages

Some problems are returned immediately as an HTTP 400, before any carrier registration starts. Fix these and resubmit your request.

Request errors (HTTP 400)

Error Message	Description
`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` but did not provide a `profile_uuid`
`Profile not found for the provided profile_uuid`	The `profile_uuid` is invalid or does not exist

Carrier registration failures

A profile or field problem affecting one carrier never blocks the other carrier and never fails the whole request. It surfaces as a FAILED status with a reason for the affected carrier only — in the enable response — while the other carrier continues. Fix the profile and retry — see Fix a failed registration and retry. Common reasons:

Reason	How to fix
Profile is missing an EIN, or the EIN is not US-issued	Add a valid US-issued EIN to the profile
`EIN must contain exactly 9 digits`	Correct the EIN to a 9-digit number
Business name, street address, city, postal code, or state is missing or invalid	Complete the address and business details on the profile
Website is missing	Add your business website to the profile
Business email or contact details are missing	Add a valid business email and contact first name, last name, title, and phone

A carrier can also reject a registration later during vetting — for example, if your business details can’t be verified. These appear as FAILED on a status check without a reason. Review your profile against the requirements above, or contact Plivo Support.

FAQ

How much does Caller Reputation cost? USD 12 per registered business per month. Billing is per business (one EIN), not per number — numbers sharing the same profile are covered under the same charge. See Pricing. When am I charged? When your business registration is approved. Registrations that fail validation or are never approved are not charged. The monthly charge is for the full month and is not prorated. 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 one monthly charge. Can I link multiple profiles to one number? No. Each number can be associated with only one business profile at a time. One carrier shows ACTIVE and the other shows FAILED. What do I do? Your calls are already branded on the active carrier. Read the reason for the failed carrier in caller_reputation_by_carrier, fix your profile, and re-enable the number to retry. See Fix a failed registration and retry. How do I remove Caller Reputation from a number? Call Update Account Phone Number and set caller_reputation to disabled. This de-registers the number. Removing the last number of a business stops its monthly billing. How long does activation take? Up to 2 business days after you enable a number. 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

Pricing

Prerequisites

How to set up Caller Reputation

Step 1: Create a Business Profile

Step 2: Enable Caller Reputation on a phone number

Step 3: Confirm activation

Status values

Merged status

API responses

Enable response — both carriers accepted

Enable response — one carrier needs a fix

Get number status — both carriers active

Status callbacks

Callback payload

Fix a failed registration and retry

Error messages

Request errors (HTTP 400)

Carrier registration failures

FAQ

​Overview

​Pricing

​Prerequisites

​How to set up Caller Reputation

​Step 1: Create a Business Profile

​Step 2: Enable Caller Reputation on a phone number

​Step 3: Confirm activation

​Status values

​Merged status

​API responses

​Enable response — both carriers accepted

​Enable response — one carrier needs a fix

​Get number status — both carriers active

​Status callbacks

​Callback payload

​Fix a failed registration and retry

​Error messages

​Request errors (HTTP 400)

​Carrier registration failures

​FAQ

​Related resources

Overview

Pricing

Prerequisites

How to set up Caller Reputation

Step 1: Create a Business Profile

Step 2: Enable Caller Reputation on a phone number

Step 3: Confirm activation

Status values

Merged status

API responses

Enable response — both carriers accepted

Enable response — one carrier needs a fix

Get number status — both carriers active

Status callbacks

Callback payload

Fix a failed registration and retry

Error messages

Request errors (HTTP 400)

Carrier registration failures

FAQ

Related resources