> For the complete documentation index, see [llms.txt](https://apidocs.api19.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.api19.com/my-inventory/mass-update-cnam.md).
# Mass update CNAM
```
https://v1.api19.com/dids/callflows/mass-update-cnam
```
### Request Body
| Parameter | Required | Description |
| --------- | -------- | -------------------------------------------------- |
| `key` | Yes | Your API token. |
| `numbers` | Yes | One or more DIDs separated by commas or new lines. |
| `cnam` | Yes | The Caller ID Name to apply to all valid DIDs. |
#### Phone number formatting
Phone numbers may be submitted using common formatting characters.
The API removes non-numeric characters before validation.
Accepted examples:
```
3035550100
13035550100
(303) 555-0100
303-555-0100
```
The API removes a leading US country code `1`, when present, and validates the remaining number as a 10-digit NANP phone number.
#### CNAM formatting
The `cnam` value may contain:
* Uppercase letters
* Lowercase letters
* Numbers
* Spaces
Special characters are removed before the value is processed.
### JSON Request Example
```
{
"numbers": "3035550100, 3035550101, 3035550102",
"cnam": "CNAM"
}
```
You may also separate numbers using new lines:
```
{
"numbers": "3035550100\n3035550101\n3035550102",
"cnam": "CNAM"
}
```
### cURL Example
```
curl https://v1.api19.com/dids/callflows/mass-update-cnam \
-d 'key=api_token' \
--data-urlencode 'numbers=3035550100
3035550101
3035550102' \
-d 'cnam=COMPANY NAME'
```
### Successful Response
The endpoint returns one result for every submitted phone number.
```
{
"status": "ok",
"data": [
{
"number": "3035550100",
"status": "ok",
"message": "CNAM updated successfully"
},
{
"number": "3035550101",
"status": "ok",
"message": "CNAM updated successfully"
},
{
"number": "3035550102",
"status": "ok",
"message": "CNAM updated successfully"
}
]
}
```
#### Response Fields
| Field | Type | Description |
| ---------------- | ------ | ---------------------------------------------------------------------- |
| `status` | string | Overall request status. A successfully processed request returns `ok`. |
| `data` | array | Individual results for each submitted phone number. |
| `data[].number` | string | Normalized 10-digit phone number. |
| `data[].status` | string | Processing result for the individual phone number. |
| `data[].message` | string | Description of the result. |
***
### Partial Success Response
A request may contain both successful and unsuccessful phone numbers.
The overall response may still return `status: ok`, while individual numbers contain an error.
```
{
"status": "ok",
"data": [
{
"number": "3035550100",
"status": "ok",
"message": "CNAM updated successfully"
},
{
"number": "123",
"status": "error",
"message": "Invalid number format"
},
{
"number": "3035550199",
"status": "error",
"message": "Number not found in your DIDs"
}
]
}
```
\
Always inspect the `status` field of every item in the `data` array. An overall `status` of `ok` does not mean that every submitted number was accepted.
***
### Error Responses
#### Missing required parameter
Returned when `numbers` or `cnam` is not included in the request.
```
{
"status": "error",
"error": "Missing required parameter"
}
```
The exact missing-parameter message may depend on the standard API validation response.
***
#### No valid numbers
```
HTTP/1.1 400 Bad Request
```
```
{
"status": "error",
"error": "No valid numbers provided"
}
```
***
#### Invalid CNAM
Returned when the CNAM is empty after unsupported characters are removed.
```
HTTP/1.1 400 Bad Request
```
```
{
"status": "error",
"error": "Invalid CNAM"
}
```
***
#### Unexpected server error
```
HTTP/1.1 500 Internal Server Error
```
```
{
"status": "error",
"error": "Unexpected error"
}
```
***
### Number-Level Errors
Individual phone numbers may return one of the following errors:
| Message | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| `Invalid number format` | The normalized phone number is not 10 digits long. |
| `Number not found in your DIDs` | The phone number does not belong to the authenticated account or an associated subaccount. |
***
### Processing Behaviour
For every valid phone number, the API creates a CNAM request containing:
| Field | Value |
| -------------- | -------------------------------- |
| Account | Authenticated account |
| DID | Normalized 10-digit phone number |
| Caller ID Name | Submitted CNAM value |
| Initial status | `pending` |
A successful API response confirms that the CNAM request was accepted for processing. It does not necessarily confirm that the downstream carrier has already completed the CNAM update.