Create a New CNAM Record

Lets you create a Caller ID record for your account which can then be assigned to any of your long code numbers. To assign a CNAM record to your number, see Assign a CNAM Record to Your Phone Number. Note that CNAM records take up to 48 hours to be approved on your account and further association with a phone number takes 5-7 business days.

CNAM Storage Rules

  • You can enter up to 15 characters for your CNAM value at least one of which is a letter.
  • In addition to spaces, the following special characters are allowed: - _ . , @ + & ' / " Please note that special characters may be removed by other network entities, and this is outside of our control.
  • While most CNAM presets can be approved, the following are not allowed and must be rejected:
    • Consist of curse words and/or is inappropriate.
    • A phone number (CNAM must be a name not a number)
    • If the CNAM preset which the customer has submitted appears to be misleading such as:
      • Political Figures or Places (Obama, Barack or The White House)
      • False or fake CNAM (Seattle Police)


POST /cnams

Body Parameters

  • value
    string REQUIRED

    The string to be displayed as the CNAM for a long code number.

Response Fields

On success, the HTTP status code in the response header is 201 Created and the response body contains a cnam object in JSON format. On error, the header status code is an error code and the response body contains an array of error objects.

Example Request

POST /v2/cnams HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

  "value": "Bob Law"


Example Request

curl -X POST -u accessKey:secretKey -H 'Content-Type': 'application/vnd.api+json' -d '{"value": "Bob Law"}' 


Example Request

This assumes that you have the Python API Wrapper installed and set up. The following example is from Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

# Instantiate the API client and create a controller for Messages
client = FlowroutenumbersandmessagingClient(basic_auth_user_name, basic_auth_password)
cnams_controller = client.cnams
print("\n--Create a CNAM Record")
result = cnams_controller.create_cnam_record('Bob Law')


Example Responses

201 Created

  "data": {
    "links": {
      "self": ""
    "type": "cnam",
    "id": "1234",
    "attributes": {
      "value": "BOB LAW",
      "is_approved": "false",
      "creation_datetime": "2018-02-28 16:18:01.670336+00:00",
      "approval_datetime": null,
      "rejection_reason": null,
      "alias": null



  "errors": [
      "detail": "Duplicate CNAM entry found on your account.",
      "id": "a082e556-cf9e-49d9-8bfe-4f0d51d6483a",
      "status": 422,
      "title": "Invalid CNAM value"