> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.youratlas.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.youratlas.com/_mcp/server.

# Upsert Caller ID Name (CNAM)

PUT https://api.youratlas.com/v1/api/business-verification/cnam
Content-Type: application/json

Saves CNAM (Caller ID Name) registration data for one or more phone numbers. Requires an approved Secondary Customer Profile. The CNAM display name is shared across all listed numbers. Returns 202 with the current profile snapshot including CNAM status.

Reference: https://docs.youratlas.com/api-reference/atlas-api/business-verification/upsert-business-verification-cnam

## Authentication

- `api-key` header (required) — Your Atlas API key. Get it from the Atlas Portal under Settings > API Keys.

## Request

### Body (application/json)

This endpoint expects a CnamUpsertRequest.

- `cnam_display_name` (string, required) — Caller ID display name (max 15 characters). Must begin with a letter and contain only letters, numbers, spaces, periods, and commas.
- `phoneNumbers` (list of string, required) — US phone numbers in E.164 format (e.g. +14155551234). Toll-free numbers are not eligible for CNAM.

## Response

### 202

Accepted — CNAM data saved, background processing started

- `secondaryProfileSid` (string, optional)
- `addressSid` (string, optional)
- `addressDocumentSid` (string, optional)
- `businessInfoEndUserSid` (string, optional)
- `ar1EndUserSid` (string, optional)
- `ar2EndUserSid` (string, optional)
- `trustProductSid` (string, optional)
- `secondaryProfileStatus` (enum, optional)
  - Allowed values: `draft`, `pending-review`, `in-review`, `twilio-approved`, `twilio-rejected`
- `trustProductStatus` (enum, optional)
  - Allowed values: `draft`, `pending-review`, `in-review`, `twilio-approved`, `twilio-rejected`
- `providerFailures` (list of ProviderFailure, optional, nullable) — Customer-actionable failures from the provider, or null
- `lastEvaluationErrors` (any, optional, nullable) — Parsed evaluation errors from Twilio, or null (legacy)
- `voiceIntegrityTrustProductSid` (string, optional) — Twilio Trust Product SID for Voice Integrity add-on
- `voiceIntegrityStatus` (enum, optional) — Current status of the Voice Integrity trust product
  - Allowed values: `draft`, `pending-review`, `in-review`, `twilio-approved`, `twilio-rejected`
- `voiceIntegrityFailures` (list of ProviderFailure, optional, nullable) — Voice Integrity provider failures, or null
- `voiceIntegrityData` (VoiceIntegrityUpsertRequest, optional, nullable) — Persisted Voice Integrity form data for rehydrating the UI
- `cnamTrustProductSid` (string, optional) — Twilio Trust Product SID for CNAM add-on
- `cnamStatus` (enum, optional) — Current status of the CNAM trust product
  - Allowed values: `draft`, `pending-review`, `in-review`, `twilio-approved`, `twilio-rejected`
- `cnamPhoneNumbers` (list of string, optional) — Phone numbers sharing the CNAM display name (E.164 format)
- `cnamFailures` (list of ProviderFailure, optional, nullable) — CNAM provider failures, or null
- `cnamData` (CnamUpsertRequest, optional, nullable) — Persisted CNAM form data for rehydrating the UI
- `formData` (BusinessVerificationFormData, optional) — Rehydrated form data from the original business info submission
- `lastUpdated` (datetime, optional)

## Errors

### 400 Bad Request Error

Bad request

- `error` (ErrorError, optional)

### 409 Conflict Error

Profile is currently being processed — retry after it settles

- `error` (ErrorError, optional)

### 500 Internal Server Error

Internal server error

- `error` (ErrorError, optional)

## Types

### ProviderFailure

A customer-actionable failure reported by the verification provider

- `code` (string, optional) — Machine-readable error code
- `message` (string, optional) — Human-readable error description

### VoiceIntegrityUpsertRequest

Voice Integrity registration request. Field names mirror Twilio's voice_integrity_information EndUser attributes.

- `use_case` (string, required) — Primary use case for voice calls
- `business_employee_count` (string, required) — Approximate number of employees
- `average_business_day_call_volume` (string, required) — Average daily outbound call volume
- `notes` (string, optional) — Optional notes for the Voice Integrity registration

### CnamUpsertRequest

CNAM (Caller ID Name) registration request. The display name is shared across all listed phone numbers.

- `cnam_display_name` (string, required) — Caller ID display name (max 15 characters). Must begin with a letter and contain only letters, numbers, spaces, periods, and commas.
- `phoneNumbers` (list of string, required) — US phone numbers in E.164 format (e.g. +14155551234). Toll-free numbers are not eligible for CNAM.

### BusinessVerificationFormData

Rehydrated form data from the original business info submission. Used by the portal to pre-fill forms without re-fetching from Twilio.

- `address` (BusinessVerificationAddress, optional, nullable)
- `businessInformation` (BusinessVerificationBusinessInfo, optional, nullable)
- `authorizedRep1` (BusinessVerificationAuthorizedRep, optional, nullable)
- `authorizedRep2` (BusinessVerificationAuthorizedRep, optional, nullable)
- `email` (string, optional)
- `friendlyName` (string, optional)

### ErrorError

- `message` (string, optional)
- `code` (string, optional)
- `requestId` (string, optional)

### BusinessVerificationAddress

- `customerName` (string, required) — Name on the address
- `street` (string, required)
- `city` (string, required)
- `region` (string, required) — State or province
- `postalCode` (string, required)
- `isoCountry` (string, required) — ISO 3166-1 alpha-2 country code (e.g. US, GB)

### BusinessVerificationBusinessInfo

- `business_type` (string, required)
- `business_registration_number` (string, required)
- `business_name` (string, required)
- `business_registration_identifier` (string, required)
- `business_identity` (enum, required)
  - Allowed values: `direct_customer`, `isv_reseller_or_partner`
- `business_industry` (string, required)
- `website_url` (string, required)
- `business_regions_of_operation` (string, required)
- `social_media_profile_urls` (string, optional) — Optional social media URL

### BusinessVerificationAuthorizedRep

- `first_name` (string, required)
- `last_name` (string, required)
- `email` (string, required)
- `phone_number` (string, required) — E.164 format (e.g. +14155551234)
- `business_title` (string, required)
- `job_position` (string, required)

## Examples

**Request**

```json
{
  "cnam_display_name": "string",
  "phoneNumbers": [
    "string"
  ]
}
```

**Response**

```json
{
  "secondaryProfileSid": "string",
  "addressSid": "string",
  "addressDocumentSid": "string",
  "businessInfoEndUserSid": "string",
  "ar1EndUserSid": "string",
  "ar2EndUserSid": "string",
  "trustProductSid": "string",
  "secondaryProfileStatus": "draft",
  "trustProductStatus": "draft",
  "providerFailures": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "lastEvaluationErrors": null,
  "voiceIntegrityTrustProductSid": "string",
  "voiceIntegrityStatus": "draft",
  "voiceIntegrityFailures": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "voiceIntegrityData": {
    "use_case": "string",
    "business_employee_count": "string",
    "average_business_day_call_volume": "string",
    "notes": "string"
  },
  "cnamTrustProductSid": "string",
  "cnamStatus": "draft",
  "cnamPhoneNumbers": [
    "string"
  ],
  "cnamFailures": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "cnamData": {
    "cnam_display_name": "string",
    "phoneNumbers": [
      "string"
    ]
  },
  "formData": {
    "address": {
      "customerName": "string",
      "street": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "isoCountry": "string"
    },
    "businessInformation": {
      "business_type": "string",
      "business_registration_number": "string",
      "business_name": "string",
      "business_registration_identifier": "string",
      "business_identity": "direct_customer",
      "business_industry": "string",
      "website_url": "string",
      "business_regions_of_operation": "string",
      "social_media_profile_urls": "string"
    },
    "authorizedRep1": {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone_number": "string",
      "business_title": "string",
      "job_position": "string"
    },
    "authorizedRep2": {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone_number": "string",
      "business_title": "string",
      "job_position": "string"
    },
    "email": "string",
    "friendlyName": "string"
  },
  "lastUpdated": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.youratlas.com/v1/api/business-verification/cnam"

payload = {
    "cnam_display_name": "string",
    "phoneNumbers": ["string"]
}
headers = {
    "api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.youratlas.com/v1/api/business-verification/cnam';
const options = {
  method: 'PUT',
  headers: {'api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"cnam_display_name":"string","phoneNumbers":["string"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.youratlas.com/v1/api/business-verification/cnam"

	payload := strings.NewReader("{\n  \"cnam_display_name\": \"string\",\n  \"phoneNumbers\": [\n    \"string\"\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.youratlas.com/v1/api/business-verification/cnam")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cnam_display_name\": \"string\",\n  \"phoneNumbers\": [\n    \"string\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.youratlas.com/v1/api/business-verification/cnam")
  .header("api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cnam_display_name\": \"string\",\n  \"phoneNumbers\": [\n    \"string\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.youratlas.com/v1/api/business-verification/cnam', [
  'body' => '{
  "cnam_display_name": "string",
  "phoneNumbers": [
    "string"
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.youratlas.com/v1/api/business-verification/cnam");
var request = new RestRequest(Method.PUT);
request.AddHeader("api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"cnam_display_name\": \"string\",\n  \"phoneNumbers\": [\n    \"string\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "cnam_display_name": "string",
  "phoneNumbers": ["string"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.youratlas.com/v1/api/business-verification/cnam")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```