---
title: "Request caller ID name"
method: POST
path: "/api/relay/rest/phone_numbers/{id}/cnam"
tags: ["Caller ID Name"]
---

# Request caller ID name

`POST /api/relay/rest/phone_numbers/{id}/cnam`

## Request

- Base URL: `https://{Your_Space_Name}.signalwire.com`
- URL: `https://{Your_Space_Name}.signalwire.com/api/relay/rest/phone_numbers/{id}/cnam`
- Auth: HTTP basic

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).

## Path parameters

- `id` string, uuid, required: Universal Unique Identifier.

## Request body

- CreatePhoneNumberCnamRequest: Request body for requesting a caller ID name for a phone number.
  - `name` string, required: 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 `201`

The request has succeeded and a new resource has been created as a result.

- PhoneNumberCnamResponse: Details and review status returned for a caller ID name request.
  - `type` 'cnam', required: The type of object. Always `cnam`.
  - `id` string, uuid, required: Universal Unique Identifier.
  - `phone_number_id` string, uuid, required: Universal Unique Identifier.
  - `name` string, required: 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.
  - `status` 'pending' | 'approved' | 'in_review' | 'rejected' | 'failed', required: Possible review statuses for a caller ID name request.
  - `reason` 'offensive_language' | 'impersonation' | 'unverified_brand' | 'implied_trusted_institution' | 'scam_wording' | 'deceptive' | 'unsupported_personal_name' | 'too_generic' | 'invalid_format' | 'unrelated_to_business' | 'needs_documentation' | 'other_compliance_concern' | 'processing_failed', required: Possible reasons a caller ID name request requires review, was rejected, or failed. Each code is explained on the `reason` field.
  - `required_action` string, nullable, required: 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_at` string, date-time, required: The date the request was created.
  - `updated_at` string, date-time, required: The date the request was last updated.

## Other responses

- `401`: Access is unauthorized.
- `404`: The server cannot find the requested resource.
- `422`: The request failed validation. See errors for details.
- `500`: An internal server error occurred.

## Changes

> 173 revisions in range; 3 could not be searched.

- **2026-08-28** `d6ae7c53d1e2`: 2 info
  - api tag `Caller ID Name` added
  - api tag `Phone Numbers` removed
- **2026-08-27** `6a0a43b3e01e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/relay/rest/phone_numbers/:id/cnam/post.md)

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) - [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalwire/apis/signalwire-rest-api/revisions/7307749294e0?raw)