Mass update CNAM

Updates the outbound Caller ID Name (CNAM) for multiple phone numbers in a single request. The submitted phone numbers must belong to the authenticated account or to one of its associated subaccount.

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
[phone]
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.