Skip to navigation
Phone NumbersCaller ID Name

Get caller ID name

View as MarkdownOpen in Claude

Retrieves the most recent caller ID name request for a phone number in your project, including its current review status. After Request a caller ID name, poll this operation until status is approved, rejected, or failed.

The response’s name is the requested name. It can differ from the name call recipients currently see while the request is pending or in_review, or after it is rejected or failed. To retrieve the caller ID name currently applied at the carrier, read cnam on the phone number with Get phone number.

Returns 404 when the phone number is not in your project or has never had a caller ID name requested.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.

Learn more about API scopes.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Path parameters

idstringRequiredformat: "uuid"
Unique ID of the phone number.

Response

The request has succeeded.
typeenum

The type of object. Always cnam.

Allowed values:
idstringformat: "uuid"
The unique identifier of the caller ID name request.
phone_number_idstringformat: "uuid"
The unique identifier of the phone number this request belongs to.
namestring<=15 characters
The requested caller ID name after normalization. SignalWire removes control characters, trims leading and trailing whitespace, collapses runs of whitespace to single spaces, and converts letters to upper case before storing the value. The stored name is at most 15 characters.
statusenum

The current state of the request.

StatusWhat it means
pendingThe name is queued for compliance review.
approvedThe name passed review and is applied at the carrier.
in_reviewThe name needs a manual decision before it can be approved or rejected.
rejectedThe name is not allowed. Submit a different name or follow required_action when provided.
failedSignalWire could not finish processing the request. Request the same name again.
Allowed values:
reasonenum or null

A machine-readable reason the request requires review, was rejected, or failed, or null when no specific reason was recorded. This value is always null while the request is pending and after it is approved. It can also be null when a request was held for review or rejected before SignalWire recorded a concern about the requested name.

CodeWhat it means
offensive_languageThe name contains language that can’t be displayed on calls.
impersonationThe name appears to impersonate another person or organization.
unverified_brandThe name can’t yet be confirmed as belonging to your business.
implied_trusted_institutionThe name could imply you represent a bank, government agency, or similar institution.
scam_wordingThe name uses wording commonly associated with scam calls.
deceptiveThe name is misleading about who is calling.
unsupported_personal_nameThe name is a personal name that isn’t supported by your verified business details.
too_genericThe name is too generic to identify you on a call.
invalid_formatThe name contains characters or formatting that can’t be displayed.
unrelated_to_businessThe name doesn’t appear to relate to your verified business.
needs_documentationDocumentation showing you’re authorized to use the name is required.
other_compliance_concernThe name didn’t pass compliance review, for a reason not covered by the other codes.
processing_failedProcessing the request failed. Request the name again.
required_actionstring or null

An action you can take to address the review, such as changing, verifying, or documenting the requested name. null when review produced no specific action.

created_atdatetime
The date the request was created.
updated_atdatetime
The date the request was last updated.

Errors

401
Unauthorized Error
404
Not Found Error
500
Internal Server Error