For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Requests the caller ID name displayed alongside a project-owned phone number on outbound calls. Caller ID name is available only for numbers whose carrier offers it. This operation sets the outbound name for your own number; to retrieve the name published for another number, use [Look up phone number](/docs/apis/rest/phone-number-lookup/lookup-phone-number) with `include=cnam`.
A `201` means SignalWire accepted the request, not necessarily that call recipients see the name yet. A new name, or one previously `rejected` or `failed`, returns with `status` set to `pending` and is queued for compliance review. Poll [Get the caller ID name](/docs/apis/rest/caller-id-name/retrieve-caller-id-name) until `status` is `approved`, `rejected`, or `failed`.
Re-requesting a name already `approved` for this phone number returns the existing request with `201` and `status` still `approved`. SignalWire re-applies that name at the carrier without another compliance review.
A phone number can have only one request awaiting a decision. Submitting a different name supersedes any earlier request with a `pending` or `in_review` status.
SignalWire normalizes `name` before validating it, so apply the length and character rules to the normalized form described on that field. When the phone number's carrier does not offer caller ID name, the operation returns `422` with an item in `errors` whose `detail` is `Caller ID name isn't available for this number.` Other `422` responses mean `name` was blank or the normalized name did not meet those rules.
Returns `404` when the phone number is not in your project.
#### 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](/docs/platform/your-signalwire-api-space).
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.
Request
This endpoint expects an object.
namestringRequired
The caller ID name you want displayed on outbound calls. SignalWire normalizes the value before
validating and storing it: control characters are removed, leading and trailing whitespace is
trimmed, runs of whitespace collapse to single spaces, and letters are converted to upper case.
For example, Acme Plumbing is stored as ACME PLUMBING.
The normalized name must be 15 characters or fewer, start with a letter or digit, and contain only
letters, digits, spaces, and &, ', ., ,, and -. Because these rules apply after
normalization, surrounding or repeated whitespace does not count against the limit.
Response
The request has succeeded and a new resource has been created as a result.
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
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error
Requests the caller ID name displayed alongside a project-owned phone number on outbound calls. Caller ID name is available only for numbers whose carrier offers it. This operation sets the outbound name for your own number; to retrieve the name published for another number, use Look up phone number with include=cnam.
A 201 means SignalWire accepted the request, not necessarily that call recipients see the name yet. A new name, or one previously rejected or failed, returns with status set to pending and is queued for compliance review. Poll Get the caller ID name until status is approved, rejected, or failed.
Re-requesting a name already approved for this phone number returns the existing request with 201 and status still approved. SignalWire re-applies that name at the carrier without another compliance review.
A phone number can have only one request awaiting a decision. Submitting a different name supersedes any earlier request with a pending or in_review status.
SignalWire normalizes name before validating it, so apply the length and character rules to the normalized form described on that field. When the phone number’s carrier does not offer caller ID name, the operation returns 422 with an item in errors whose detail is Caller ID name isn't available for this number. Other 422 responses mean name was blank or the normalized name did not meet those rules.
Returns 404 when the phone number is not in your project.
Permissions
The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.
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.
