Studies have shown that people are more likely to pick up the phone when they recognize the name of the caller. The CNAM storage API allows you to store up to 15 characters as a display name that you can associate with your Flowroute long code number for outbound calls. To learn more about CNAM storage, CNAM dips (for inbound calls), and the business benefits that the service can offer, see What is CNAM and how can it work for your business?

New to Number Management with Flowroute?

This guide assumes that you have an activated Flowroute account and have followed the instructions on Purchase Your First Flowroute Phone Number.


Validate and create an CNAM record

The Flowroute CNAM Storage API allows you to post a display name of up to 15 characters that you can then associate with a US long code (or local) number on your Flowroute account. Note that a CNAM preset takes up to 48 hours of approval time, and an additional 5-7 business days for the phone number association to take effect.

For the Manage method of creating a Caller ID Name (CNAM) record, see Set an Outbound Caller ID Name aka CNAM Storage. In this tutorial, we will show you how to add a CNAM record to your account using the Flowroute API v2:

CNAM Storage Rules

  • You can enter up to 15 characters for your CNAM value at least one of which is a letter.
  • 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)

Request via cURL

  1. Open a command shell session.
  2. If you haven't installed cURL previously, download your specific source package here.
  3. Copy the following example POST request.
  4. curl -X POST https://api.flowroute.com/v2/cnams -u accessKey:secretKey -d '{"value": "Pacific Dental"}' -H 'Content-Type':'application/vnd+api.json'
  5. Replace accessKey:secretKey with your API credentials.
  6. In the JSON body parameters section of your cURL request right after the cURL -d flag, replace value with your preferred display name following the Body Parameters section of "Create a New CNAM Record".
  7. Press Enter.


To avoid errors, make sure to:

  • Enter your API credentials correctly.
  • Use vertical quotes in your request. Learn more about Unicode and and ISO 10646 standards in ASCII and Unicode quotation marks.
  • Use a backslash (\) at the end of lines to break up a long cURL statement into easier-to-read lines if you're in a UNIX environment. If you're using Windows, replace any backslash at the end of lines with the caret (^) character. Here's a great guide for installing and using cURL.

Request via Python

  1. To begin, follow the Requirements and Installation sections of the library guide.
  2. Open up your preferred text editor and start writing Python code.
  3. vim cnam-test.py
  4. Import the following required libraries.
  5. import pprint
    import os
    import json
    from flowroutenumbersandmessaging.flowroutenumbersandmessaging_client import FlowroutenumbersandmessagingClient
  6. Assign your Flowroute accessKey and secretKey to the following variables or set them as environment variables.
  7. basic_auth_user_name = "YOUR_FR_ACCESS_KEY"
    basic_auth_password = "YOUR_FR_SECRET_KEY"
  8. Next, instantiate the API Client and the cnams controllers.
  9. client = FlowroutenumbersandmessagingClient(basic_auth_user_name, basic_auth_password)
    cnams_controller = client.cnams
  10. Lastly, specify your body parameters and invoke the Python library v3 create_cnam_record method.
  11. print("\n--Create a CNAM Record")
    cnam_value = 'Regence Inc'
    result = cnams_controller.create_cnam_record(cnam_value)
    print("\nNOTE: Newly created CNAM records need to be approved first before "
          "they can be associated with your long code number.")
  12. You're done coding, at least for the CNAM record creation portion of this tutorial. Save the file and run it.
  13. python cnam-test.py

Flowroute API Create a New CNAM Record Response

On success, the HTTP status code in the response header is 201 CREATED and the response body contains the newly created cnam object in JSON format. Make a note of the id of the CNAM record in the JSON response. You will need that for the next portion.

  "data": {
    "links": {
      "self": "https://api.flowroute.com/v2/cnams/1234"
    "type": "cnam",
    "id": "12345",
    "attributes": {
      "value": "REGENCE INC",
      "is_approved": "false",
      "creation_datetime": "2018-07-16T16:18:01Z",
      "approval_datetime": null,
      "rejection_reason": null


Associate the CNAM record with your long code number

A CNAM record takes up to 48 hours to be approved on your account. Once approved, you may associate your CNAM record with any long code Flowroute number that you own. Note that Manage allows for association with an unapproved CNAM record, while the API does not. The phone number and CNAM association will take 5-7 business days before taking effect.

Request via cURL

  1. To assign your approved CNAM record as the caller display name on your long code number, copy the following example PATCH request.
  2. curl https://api.flowroute.com/v2/numbers/16463439697/relationships/cnam/12345 -X PATCH -u accessKey:secretKey
  3. Replace accessKey:secretKey with your API credentials.
  4. In the path parameter section of your cURL request right after numbers, https://api.flowroute.com/v2/numbers, replace the example phone number with the id of your long code number and the example CNAM ID after cnams with the id of the CNAM record you want to assign to your phone number.
  5. Press Enter.