- 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:
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) |
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 |
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 |
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.
