docs(rest): add the CNAM (caller ID name) API for phone numbers

fern/docs.yml

@@ -341,6 +341,30 @@ redirects:
   - source: /docs/platform/ai/no-code-agents
     destination: /docs/platform/ai
 
+  # Phone number management references are grouped by customer workflow.
+  - source: /docs/apis/rest/phone-numbers/retrieve-caller-id-name
+    destination: /docs/apis/rest/caller-id-name/retrieve-caller-id-name
+  - source: /docs/apis/rest/phone-numbers/request-caller-id-name
+    destination: /docs/apis/rest/caller-id-name/request-caller-id-name
+  - source: /docs/apis/rest/phone-numbers/clear-caller-id-name
+    destination: /docs/apis/rest/caller-id-name/clear-caller-id-name
+  - source: /docs/apis/rest/phone-numbers/assign-e-911-address
+    destination: /docs/apis/rest/e-911-addresses/assign-e-911-address
+  - source: /docs/apis/rest/phone-numbers/remove-e-911-address
+    destination: /docs/apis/rest/e-911-addresses/remove-e-911-address
+  - source: /docs/apis/rest/phone-numbers/assign-resource-phone-route
+    destination: /docs/apis/rest/phone-routes/assign-resource-phone-route
+  - source: /docs/apis/rest/phone-numbers/lookup-phone-number
+    destination: /docs/apis/rest/phone-number-lookup/lookup-phone-number
+  - source: /docs/apis/rest/number-group-membership/list-number-group-memberships
+    destination: /docs/apis/rest/number-groups/list-number-group-memberships
+  - source: /docs/apis/rest/number-group-membership/create-number-group-membership
+    destination: /docs/apis/rest/number-groups/create-number-group-membership
+  - source: /docs/apis/rest/number-group-membership/retrieve-number-group-membership
+    destination: /docs/apis/rest/number-groups/retrieve-number-group-membership
+  - source: /docs/apis/rest/number-group-membership/delete-number-group-membership
+    destination: /docs/apis/rest/number-groups/delete-number-group-membership
+
   # Webhook reference pages moved out of their per-resource sections into one
   # top-level Webhooks section. A callback like the SWAIG tool webhook fires for
   # voice AI, Amazon Bedrock, sidecar agents, and text conversations alike, so

fern/products/apis/apis.yml

@@ -125,23 +125,32 @@ navigation:
               - whatsAppTemplates
             contents: []
           - shortCodes
-      - section: Phone Number Management
+      - section: Phone Numbers
         skip-slug: true
         contents:
-          - section: Phone Numbers
+          - section: Inventory
+            slug: phone-numbers
             referenced-packages:
               - phoneNumbers
               - importedPhoneNumbers
+            contents: []
+          - section: Lookup
+            slug: phone-number-lookup
+            referenced-packages:
               - phoneNumberLookup
-              - phoneRoutes
             contents: []
-          - section: E911 Addresses
+          - callerIdName
+          - verifiedCallerId
+          - section: E911
+            slug: e-911-addresses
             referenced-packages:
               - e911Addresses
             contents: []
-          - numberGroups
-          - numberGroupMembership
-          - verifiedCallerId
+          - section: Number Groups
+            referenced-packages:
+              - numberGroups
+              - numberGroupMembership
+            contents: []
       - section: Platform
         skip-slug: true
         contents:
@@ -170,6 +179,7 @@ navigation:
             referenced-packages:
               - resources
             contents: []
+          - phoneRoutes
           - section: Addresses
             referenced-packages:
               - addresses

fern/products/platform/pages/calling/voice/caller-id-and-cnam.mdx

@@ -18,11 +18,33 @@ At this point, both a CLID number and CNAM text are usually delivered to the rec
 
 ## Set CNAM for PSTN numbers
 
+If your number's carrier offers caller ID name (CNAM), you can set the name in your SignalWire Dashboard or with the REST API.
 
-To enable or modify a CNAM for a SignalWire phone number, open a support ticket by clicking the **Create a ticket** option, located under the **Support** button in the upper right corner of your [SignalWire Dashboard](https://my.signalwire.com/dashboard).
+<llms-ignore>
+
+In the SignalWire Dashboard, click **Phone Numbers** in the sidebar, select the number, and edit the **Caller ID Name** field.
+
+</llms-ignore>
+
+To set the name over the API, call [Request a caller ID name](/docs/apis/rest/caller-id-name/request-caller-id-name):
+
+<EndpointRequestSnippet endpoint="POST /api/relay/rest/phone_numbers/{id}/cnam" />
+
+A new name, or one previously rejected or failed, is queued for compliance review and returns with a `status` of `pending`.
+If the name is already approved for the number, the request returns that approval and re-applies the name without another review.
+Poll [Get the caller ID name](/docs/apis/rest/caller-id-name/retrieve-caller-id-name) while a request is `pending` or `in_review`.
+After approval, the name appears as `cnam` on the phone number and can be displayed to call recipients.
+To remove a name, call [Clear the caller ID name](/docs/apis/rest/caller-id-name/clear-caller-id-name).
+
+### If CNAM isn't available for your number
+
+Not every carrier offers CNAM.
+If the API returns `422` and an item in `errors` has the `detail` `Caller ID name isn't available for this number.`, use the support process below.
+Other `422` responses indicate a problem with the requested name that you should correct before trying again.
+For those numbers, open a support ticket by clicking the **Create a ticket** option, located under the **Support** button in the upper right corner of your [SignalWire Dashboard](https://my.signalwire.com/dashboard).
 To display a company or personal name, you must provide either a copy of ID for a personal name, or proof of company through documents with your name listed for the company name.
 
-**In your ticket, please include the following:**
+**In your ticket, include the following:**
 
 - The phone number that needs a CNAM
 - Name to display for the CNAM

fern/products/platform/pages/calling/voice/resolving-spam-labels.mdx

@@ -30,9 +30,10 @@ Because these signals come from different sources, resolving a label usually tak
 
 <Steps>
 
-### Request A attestation and CNAM from SignalWire Support
+### Set CNAM and request A attestation
 
-SignalWire handles the carrier-side pieces through a single support ticket, [STIR/SHAKEN](/docs/platform/voice/stir-shaken) attestation and [CNAM](/docs/platform/voice/how-to-set-caller-id-or-cnam).
+Set CNAM directly when it is available for your number, then open a SignalWire Support ticket for [STIR/SHAKEN](/docs/platform/voice/stir-shaken) A attestation.
+If caller ID name is not available through the Dashboard or REST API, include the requested CNAM values in the same support ticket.
 
 **A attestation** is the highest STIR/SHAKEN attestation level. 
 It confirms that SignalWire has identified you and that you are authorized to use the calling numbers. 
@@ -41,6 +42,9 @@ As part of that vetting, SignalWire may ask you to complete Know Your Customer (
 
 **CNAM** is the caller ID name that can display alongside your number on supported networks. 
 A missing, outdated, or generic CNAM, or one inherited from a previous user of the number, makes recipients more likely to distrust the call or report it as spam.
+If your number's carrier offers CNAM, set the name in your Dashboard or with [Request caller ID name](/docs/apis/rest/caller-id-name/request-caller-id-name).
+If the API returns `422` and an item in `errors` has the `detail` `Caller ID name isn't available for this number.`, include the requested name in the support ticket below.
+Other `422` responses indicate a problem with the requested name that you should correct before trying again.
 
 Open a support ticket from the **Support** button in your [SignalWire Dashboard](https://my.signalwire.com/dashboard) and choose **Create a ticket**. Include:
 
@@ -49,9 +53,11 @@ Open a support ticket from the **Support** button in your [SignalWire Dashboard]
 - The numbers you use for outbound calling
 - A short description of your calling use case
 - Confirmation that the numbers are assigned to your business or application
-- A spreadsheet of the numbers and requested CNAM values (format below)
+- If caller ID name is not available through the Dashboard or REST API, a spreadsheet of the numbers and requested CNAM values
 - Evidence of the label: screenshots, the carrier or app where it appears (such as AT&T, Verizon, T-Mobile, Samsung Smart Call, or Hiya), and an example call date and time
 
+If you need SignalWire Support to set CNAM, use this spreadsheet format:
+
 | Phone number | Requested CNAM |
 | ------------ | -------------- |
 | +15551234567 | BUSINESSNAME   |
@@ -73,7 +79,8 @@ Follow these guidelines when choosing a CNAM value:
 
 </Info>
 
-Once any required KYC is approved, SignalWire Support reviews the account for A attestation and submits your CNAM updates. For full details on caller ID and CNAM, see [Caller ID & CNAM](/docs/platform/voice/how-to-set-caller-id-or-cnam).
+Once any required KYC is approved, SignalWire Support reviews the account for A attestation and processes any CNAM values included in the ticket.
+For full details on caller ID and CNAM, see [Caller ID & CNAM](/docs/platform/voice/how-to-set-caller-id-or-cnam).
 
 ### Register with Free Caller Registry
 

fern/products/platform/pages/platform/phone-numbers/e911.mdx

@@ -74,9 +74,9 @@ send a `DELETE` request to the same endpoint.
 
 For full request and response details,
 see the [E911 Addresses](/docs/apis/rest/e-911-addresses/list-addresses) reference for address operations,
-and [Assign an E911 address](/docs/apis/rest/phone-numbers/assign-e-911-address)
-and [Remove an E911 address](/docs/apis/rest/phone-numbers/remove-e-911-address)
-under the Phone Numbers reference.
+and [Assign an E911 address](/docs/apis/rest/e-911-addresses/assign-e-911-address)
+and [Remove an E911 address](/docs/apis/rest/e-911-addresses/remove-e-911-address)
+in the E911 reference.
 
 <Info title="Compatibility API">
 

fern/products/platform/pages/platform/phone-numbers/what-is-e164.mdx

@@ -50,6 +50,5 @@ the first digit after the plus sign must be a number between 1 and 9.
 ^\+[1-9]\d{1,14}$
 ```
 
-To ensure the formatted number is a valid number, you can use the [SignalWire Phone Number Lookup API](/docs/apis/rest/phone-numbers/lookup-phone-number)
+To ensure the formatted number is a valid number, you can use the [SignalWire Phone Number Lookup API](/docs/apis/rest/phone-number-lookup/lookup-phone-number)
 to verify the number's validity and retrieve additional information about it.
-

specs/signalwire-rest/main.tsp

@@ -114,6 +114,7 @@ using TypeSpec.OpenAPI;
 @tagMetadata(NUMBER_GROUPS_TAG, NUMBER_GROUPS_TAG_METADATA)
 @tagMetadata(NUMBER_GROUP_MEMBERSHIP_TAG, NUMBER_GROUP_MEMBERSHIP_TAG_METADATA)
 @tagMetadata(PHONE_NUMBERS_TAG, PHONE_NUMBERS_TAG_METADATA)
+@tagMetadata(CALLER_ID_NAME_TAG, CALLER_ID_NAME_TAG_METADATA)
 @tagMetadata(IMPORTED_PHONE_NUMBERS_TAG, IMPORTED_PHONE_NUMBERS_TAG_METADATA)
 @tagMetadata(PHONE_NUMBER_LOOKUP_TAG, PHONE_NUMBER_LOOKUP_TAG_METADATA)
 @tagMetadata(RECORDINGS_TAG, RECORDINGS_TAG_METADATA)

specs/signalwire-rest/relay-rest/addresses/main.tsp

@@ -32,7 +32,7 @@ namespace SignalWireAPI.RelayRest.Addresses {
     @operationId("create_address")
     @summary("Create E911 address")
     @doc("""
-      Creates a physical E911 service address that can be assigned to an owned phone number for emergency calling. Use it before [Assign an E911 address to a phone number](/docs/apis/rest/phone-numbers/assign-e-911-address) when emergency services need the caller's registered street location. Do not use this endpoint for a resource address or SIP URI.
+      Creates a physical E911 service address that can be assigned to an owned phone number for emergency calling. Use it before [Assign an E911 address to a phone number](/docs/apis/rest/e-911-addresses/assign-e-911-address) when emergency services need the caller's registered street location. Do not use this endpoint for a resource address or SIP URI.
 
       When `emergency_enabled=true` and the address is in the US (`country` = `US`), the address is validated against the carrier. A valid or auto-corrected address is stored (`validated: true`). An address the carrier cannot validate — or a correctable address when `auto_correct_address=false` — is rejected with a `422` whose body includes an `errors` array and a `candidates` array of suggested addresses (each with `street_number`, `street_name`, `city`, `state`, `postal_code`). Carrier validation applies to US addresses only: a non-US address is stored normally, with `emergency_enabled` returned as `false`. Requests without `emergency_enabled` are stored without carrier validation.
 
@@ -62,7 +62,7 @@ namespace SignalWireAPI.RelayRest.Addresses {
     @operationId("update_address")
     @summary("Update E911 address")
     @doc("""
-      Changes a physical E911 service location and performs carrier validation when requested. Assigning the updated location to a phone number remains a separate [phone-number operation](/docs/apis/rest/phone-numbers/assign-e-911-address).
+      Changes a physical E911 service location and performs carrier validation when requested. Assigning the updated location to a phone number remains a separate [phone-number operation](/docs/apis/rest/e-911-addresses/assign-e-911-address).
 
       When `emergency_enabled=true` and the address is in the US (`country` = `US`), the address is validated against the carrier. A valid or auto-corrected address is stored (`validated: true`). An address the carrier cannot validate — or a correctable address when `auto_correct_address=false` — is rejected with a `422` whose body includes an `errors` array and a `candidates` array of suggested addresses (each with `street_number`, `street_name`, `city`, `state`, `postal_code`). Carrier validation applies to US addresses only: a non-US address is stored normally, with `emergency_enabled` returned as `false`. Requests without `emergency_enabled` are stored without carrier validation.
 
@@ -79,7 +79,7 @@ namespace SignalWireAPI.RelayRest.Addresses {
     @operationId("delete_address")
     @summary("Delete E911 address")
     @doc("""
-      Permanently deletes a physical E911 service address by ID. Use it when the emergency location record is no longer needed; use [Remove the E911 address from a phone number](/docs/apis/rest/phone-numbers/remove-e-911-address) when only the number's assignment should be removed. Resource addresses and SIP Addresses have separate delete operations.
+      Permanently deletes a physical E911 service address by ID. Use it when the emergency location record is no longer needed; use [Remove the E911 address from a phone number](/docs/apis/rest/e-911-addresses/remove-e-911-address) when only the number's assignment should be removed. Resource addresses and SIP Addresses have separate delete operations.
 
       ${tokenPermissions<"_Numbers_">}
       """)

specs/signalwire-rest/relay-rest/number-groups/main.tsp

@@ -19,7 +19,7 @@ namespace SignalWireAPI.RelayRest.NumberGroups {
     @operationId("list_number_groups")
     @summary("List number groups")
     @doc("""
-      Lists the Number Groups in your SignalWire project. A Number Group organizes owned phone numbers into a sender pool and can preserve the same sender for repeated outbound traffic with `sticky_sender`. Use [List number group memberships](/docs/apis/rest/number-group-membership/list-number-group-memberships) to see which numbers belong to a group. Results are sorted by creation date, most recent first.
+      Lists the Number Groups in your SignalWire project. A Number Group organizes owned phone numbers into a sender pool and can preserve the same sender for repeated outbound traffic with `sticky_sender`. Use [List number group memberships](/docs/apis/rest/number-groups/list-number-group-memberships) to see which numbers belong to a group. Results are sorted by creation date, most recent first.
 
       ${tokenPermissions<"_Numbers_">}
       """)
@@ -32,7 +32,7 @@ namespace SignalWireAPI.RelayRest.NumberGroups {
     @operationId("create_number_group")
     @summary("Create number group")
     @doc("""
-      Creates a named pool for project-owned phone numbers, with optional sticky-sender behavior. Use it when outbound traffic should select from a managed group rather than one fixed number; add numbers afterward with [Create number group membership](/docs/apis/rest/number-group-membership/create-number-group-membership). This operation does not purchase phone numbers.
+      Creates a named pool for project-owned phone numbers, with optional sticky-sender behavior. Use it when outbound traffic should select from a managed group rather than one fixed number; add numbers afterward with [Create number group membership](/docs/apis/rest/number-groups/create-number-group-membership). This operation does not purchase phone numbers.
 
       ${tokenPermissions<"_Numbers_">}
       """)
@@ -137,7 +137,7 @@ namespace SignalWireAPI.RelayRest.NumberGroupMemberships {
     @operationId("retrieve_number_group_membership")
     @summary("Get number group membership")
     @doc("""
-      Retrieves one Number Group Membership by ID so you can inspect the link between a project phone number and its sender pool. Use [List number group memberships](/docs/apis/rest/number-group-membership/list-number-group-memberships) to discover memberships for a group.
+      Retrieves one Number Group Membership by ID so you can inspect the link between a project phone number and its sender pool. Use [List number group memberships](/docs/apis/rest/number-groups/list-number-group-memberships) to discover memberships for a group.
 
       ${tokenPermissions<"_Numbers_">}
       """)