> ## 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

<Info title="TL;DR">
  * **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](/messaging/api/10dlc/profile) with your EIN, then enable `caller_reputation` on each number via [Update Account Phone Number](/numbers/account-phone-numbers#update-an-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
</Info>

<Note>
  Caller Reputation is currently in **early access beta** and available only for **US local and toll-free numbers**.
</Note>

## 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](/messaging/api/10dlc/profile#create-a-profile). 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:

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

<Note>
  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](/messaging/api/10dlc/profile) and re-enable the number.
</Note>

### Step 2: Enable Caller Reputation on a phone number

Call the [Update Account Phone Number](/numbers/account-phone-numbers#update-an-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.

<Note>
  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.
</Note>

### Step 3: Confirm activation

Call the [Get Account Phone Number](/numbers/account-phone-numbers#get-an-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-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](#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:

1. If any carrier is `ACTIVE` → **`ACTIVE`**
2. Else if any carrier is `PENDING` → **`PENDING`**
3. Else if any carrier is `FAILED` → **`FAILED`**
4. 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.

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

## 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                                                                             |

<Note>
  `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](#error-messages).
</Note>

### Enable response — both carriers accepted

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

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

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

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

1. **Find the cause.** The enable response from [Update Account Phone Number](/numbers/account-phone-numbers#update-an-account-phone-number) includes a `reason` for any carrier that fails validation — note it. A later status check from [Get Account Phone Number](/numbers/account-phone-numbers#get-an-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](#error-messages).
2. **Fix your profile.** Correct the issue on your Business Profile with the [Update Profile API](/messaging/api/10dlc/profile) — for example, set `number_of_employees` or correct the EIN.
3. **Re-enable the number.** Call [Update Account Phone Number](/numbers/account-phone-numbers#update-an-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.

<Note>
  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](#pricing).
</Note>

## 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](#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](https://support.plivo.com).

## 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](#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](#fix-a-failed-registration-and-retry).

**How do I remove Caller Reputation from a number?**
Call [Update Account Phone Number](/numbers/account-phone-numbers#update-an-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.

## Related resources

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