> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller Reputation

> Register your business identity with US carriers to build trust and reduce spam flagging on outbound calls

> [!NOTE]
>
> * **What:** Register your US business with carriers so outbound calls display your business name instead of a spam flag.
> * **When:** Early-access beta, US numbers only. It reduces spam flagging but doesn't guarantee it.

> [!NOTE]
>
> 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:

1. **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.
2. **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](#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](https://plivo.com/docs/messaging/api/10dlc/profile.md#update-a-profile) with `enable_caller_reputation` set to `true`.
* **While creating a profile:** pass the same fields to the [Create Profile API](https://plivo.com/docs/messaging/api/10dlc/profile.md#create-a-profile) 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](#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.

```json theme={null}
{
  "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"
  }
}
```

> [!NOTE]
>
> 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](https://plivo.com/docs/messaging/api/10dlc/profile.md#retrieve-a-profile), 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](https://plivo.com/docs/numbers/account-phone-numbers.md#update-an-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.

```json theme={null}
{
  "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](https://plivo.com/docs/numbers/account-phone-numbers.md#get-an-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](https://plivo.com/docs/voice/concepts/signature-validation.md) — 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 |

```text theme={null}
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`.

> [!NOTE]
>
> 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](https://plivo.com/docs/messaging/api/10dlc/profile.md#update-a-profile), 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](https://plivo.com/docs/numbers/account-phone-numbers.md#update-an-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:

1. Disable `caller_reputation` on every number under the profile for the networks you're deregistering.
2. Call the [Update Profile API](https://plivo.com/docs/messaging/api/10dlc/profile.md#update-a-profile) 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](#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.

## Related resources

* [STIR/SHAKEN](https://plivo.com/docs/voice/concepts/stir-shaken.md) — Call authentication and attestation
* [Verified Caller ID](https://plivo.com/docs/voice/concepts/verified-caller-id.md) — Verify external numbers for use as caller ID
* [Profile API](https://plivo.com/docs/messaging/api/10dlc/profile.md) — Create and manage business profiles
* [Account Phone Numbers API](https://plivo.com/docs/numbers/account-phone-numbers.md) — Manage your Plivo phone numbers