Get caller ID name | SignalWire

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.

Clear caller ID name doesn’t delete request records, so this operation can still return one after a clear. Until the carrier confirms the removal, a request that is pending or in_review is still returned unchanged. After confirmation, those requests are canceled and no longer returned, but the most recent earlier request with another status, such as approved, is returned instead. To check whether a clear has taken effect, read cnam on the phone number, which becomes null.

Returns 404 when the phone number is not in your project or has no caller ID name request to return.

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.

Status	What it means
`pending`	The name is queued for compliance review.
`approved`	The name passed review and is applied at the carrier.
`in_review`	The name needs a manual decision before it can be approved or rejected.
`rejected`	The name is not allowed. Submit a different name or follow `required_action` when provided.
`failed`	SignalWire 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.

Code	What it means
`offensive_language`	The name contains language that can’t be displayed on calls.
`impersonation`	The name appears to impersonate another person or organization.
`unverified_brand`	The name can’t yet be confirmed as belonging to your business.
`implied_trusted_institution`	The name could imply you represent a bank, government agency, or similar institution.
`scam_wording`	The name uses wording commonly associated with scam calls.
`deceptive`	The name is misleading about who is calling.
`unsupported_personal_name`	The name is a personal name that isn’t supported by your verified business details.
`too_generic`	The name is too generic to identify you on a call.
`invalid_format`	The name contains characters or formatting that can’t be displayed.
`unrelated_to_business`	The name doesn’t appear to relate to your verified business.
`needs_documentation`	Documentation showing you’re authorized to use the name is required.
`other_compliance_concern`	The name didn’t pass compliance review, for a reason not covered by the other codes.
`processing_failed`	Processing 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

500

Internal Server Error