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’s Caller Reputation service is powered by two major caller identification providers:
- First Orion — covers T-Mobile subscribers
- Hiya — covers AT&T subscribers
When Caller Reputation is active on a number, calls from that number display your registered business name on supported devices across these networks.
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 (Employer Identification Number)
- Business address
- Business website
- Contact information
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 a profile, you can reuse it.
Your profile must include your business name, EIN, address, website, and contact details.
Step 2: Enable Caller Reputation on a phone number
Use the Update Account Phone Number endpoint with the following parameters:
caller_reputation — set to enabledprofile_uuid — your business profile UUIDcaller_reputation_callback_url — (optional) URL to receive status update notificationscaller_reputation_callback_method — (optional) GET or POST (default: POST)
This triggers the Caller Reputation registration process with First Orion and Hiya.
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
Check the registration status by calling the Get Account Phone Number endpoint. The caller_reputation_status field shows the current state of the registration.
If you provided a caller_reputation_callback_url, you’ll also receive notifications when the status changes.
Status values
| Status | Description |
|---|
PENDING | Registration submitted and being processed by carrier partners |
ACTIVE | Registration complete — your business name displays on outbound calls |
FAILED | Registration was rejected. Check your profile details and retry |
NOT_ENROLLED | The number is not eligible for Caller Reputation |
null | No Caller Reputation registration has been initiated for this number |
Activation can take up to 2 business days after linking a profile to a number. Only one profile can be associated per EIN.
Error messages
Plivo validates your request before submitting it to carrier partners. If validation fails, the API returns an HTTP 400 response with one of the following error messages.
Profile and EIN validation
| Error Message | Description |
|---|
Profile not found for the provided profile_uuid | The profile_uuid is invalid or does not exist |
profile_uuid is required when caller_reputation is enabled | You set caller_reputation to enabled but did not provide a profile_uuid |
Profile does not have an EIN (tax ID) | The linked profile is missing an EIN |
caller_reputation requires a US-issued EIN. Profile EIN country: {ein_issuing_country} | The EIN on the profile was not issued in the US. Caller Reputation only supports US-issued EINs |
EIN must contain exactly 9 digits | The EIN is not a valid 9-digit number |
Business details validation
| Error Message | Description |
|---|
Company name must be between 4 and 256 characters | The business name on the profile is too short or too long |
Street address is required | The profile is missing a street address |
City is required in the profile | The profile is missing a city |
Postal code must be between 5 and 10 characters | The postal code length is outside the allowed range |
Country must be a 2-character ISO code | The country code on the profile is not a valid 2-character ISO code |
{value} is not a valid US state code | The state code on the profile is not a recognized US state |
| Error Message | Description |
|---|
Contact first name is required for caller_reputation | The profile is missing a contact first name |
A valid contact email is required for caller_reputation | The contact email on the profile is missing or invalid |
Contact phone must be in E.164 format | The contact phone number is missing or not in E.164 format (e.g., +14155551234) |
Number eligibility
| Error Message | Description |
|---|
caller_reputation is only supported for US numbers | The phone number is not a US number. Caller Reputation only supports US local and toll-free numbers |
FAQ
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 will display the same business name.
Can I link multiple profiles to one number?
No. Each number can only be associated with one business profile at a time.
How do I remove Caller Reputation from a number?
Use the Update Account Phone Number endpoint and set caller_reputation to disabled. This de-registers the number from Caller Reputation.
How long does activation take?
Activation typically takes up to 2 business days after linking a profile to 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. However, call behavior, volume patterns, and recipient feedback can still influence spam classification by carriers and device-level apps.
