Skip to main content
This guide covers CNAM (Caller ID Name) lookup for US phone numbers on Plivo.

​
Overview

CNAM (Caller ID Name) is a feature in the US public telephone network that associates phone numbers with registered names. When someone receives a call, their carrier queries the Line Information Database (LIDB) and displays the caller’s registered name. Plivo provides CNAM lookup on US phone numbers for:
  • Inbound Voice API calls
  • Inbound Zentrunk (SIP trunking) calls

​
How CNAM Works

  1. Caller dials your Plivo US number
  2. Plivo queries the LIDB for the caller’s registered name
  3. CNAM data is included in the call callback payload
  4. Your application can display or use the caller name

​
Enable CNAM Lookup

​
Account-Level Default

Set the default CNAM setting for all newly rented US numbers:
  1. Navigate to Phone Numbers > Settings
  2. Enable or disable CNAM lookup as the default
  3. This setting applies to numbers rented after the change

​
When Purchasing Numbers

  1. Go to Phone Numbers > Buy Numbers
  2. Search for US numbers
  3. During purchase, select CNAM lookup configuration
  4. If you skip configuration, the account default applies

​
Update Existing Numbers

Single number:
  1. Go to Phone Numbers > Active
  2. Click on the US phone number
  3. Update CNAM lookup setting
  4. Save
Multiple numbers:
  1. Go to Phone Numbers > Active
  2. Select numbers using checkboxes
  3. Click Choose Action > Update CNAM
  4. Apply changes

​
Check CNAM Status

​
Via Console

  1. Navigate to Phone Numbers > Active
  2. View CNAM lookup status column for US numbers
  3. Use filters to show only CNAM-enabled or disabled numbers

​
Via API

Use the cnam_lookup parameter of the AccountPhoneNumber API: 
GET /v1/Account/{auth_id}/Number/{number}/
Response includes: 
{
  "number": "14151234567",
  "cnam_lookup": true,
  ...
}

​
Filter Numbers by CNAM Status

Use the cnam_lookup parameter in the List Account Phone Numbers API: 
GET /v1/Account/{auth_id}/Number/?cnam_lookup=true

​
CNAM in Callbacks

When CNAM lookup is enabled, inbound call callbacks include:
ParameterDescription
cnam_lookup_resultThe caller’s registered name (if found)
Note: CNAM data may not be available for all callers. Mobile numbers and some VoIP services may not have CNAM records.

​
Pricing

CNAM lookup is charged per inbound call when enabled on a number.

​
Best Practices

​
Enable Selectively

Only enable CNAM on numbers where caller identification provides business value:
  • Customer service lines
  • Sales hotlines
  • Support numbers

​
Cost Management

  • Disable CNAM on high-volume numbers if caller name isn’t needed
  • Monitor CNAM charges in your monthly invoice
  • Use account-level defaults to control costs

​
Handle Missing Data

Your application should gracefully handle cases where:
  • CNAM lookup returns no result
  • Caller has no registered name
  • Database timeout occurs

​
Limitations

LimitationDescription
US onlyCNAM lookup is only available for US phone numbers
Inbound onlyOnly works for incoming calls, not outbound
Database coverageNot all phone numbers have CNAM records
AccuracyCNAM data may be outdated or incorrect