Request caller ID name

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.

Learn more about API scopes.

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)

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.

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.

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

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.

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.

$	curl -X POST https://{your_space_name}.signalwire.com/api/relay/rest/phone_numbers/id/cnam \
>	-H "Content-Type: application/json" \
>	-u "<project_id>:<api_token>" \
>	-d '{
>	"name": "Acme Plumbing"
>	}'

1	{
2	"type": "cnam",
3	"id": "b6a4f0c2-3f1e-4c9a-9c1b-7f2e5a1d8c40",
4	"phone_number_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5	"name": "ACME PLUMBING",
6	"status": "approved",
7	"reason": null,
8	"required_action": null,
9	"created_at": "2024-01-15T09:30:00Z",
10	"updated_at": "2024-01-15T09:30:00Z"
11	}