Menu

Expand
Rate this page:

Brand Your Calls Using CNAM (Public Beta)

Overview

CNAM stands for Caller ID Name. CNAM is a feature in the United States public telephone network that identifies an incoming caller by a personal or business name associated with the originating phone number. CNAM is registered by the EndUser assigned the phone number through their Telephony Service Provider (Twilio).

Please note that, at this time, only Twilio phone numbers from the United States fully support CNAM lookups. Other countries, including Canada, are not supported.

Onboarding

There are two different options for enabling CNAM on your phone number(s):

  1. Using the Twilio Console
  2. Twilio's Trust Hub REST API.

Please note CNAM:

  • Can be a maximum of 15 characters.
  • Must be a unique name or value, cannot be a generic value such as a City/State.
  • Should begin with a letter and can only contain letters, numbers, periods, commas and spaces
  • If no Caller Name (CNAM) is set for the number, the City and State of the number is the default display along with phone number.

Note: At this time, you are unable to update Toll-Free numbers CNAM via the Twilio Console or API. To update the CNAM on a Toll-Free number, please contact support.

CNAM Onboarding in the Twilio Console

  1. Create a Business Profile in the Console's Trust Hub and submit for vetting.
    • If you are an ISV, then you would need to create a Secondary Business Profile for your customer(s).
  2. Assign phone numbers in your account to the Business Profile.
    • This associates a single identity with the phone numbers.
  3. Create a CNAM Trust Product instance that is associated with your in the Trust Hub and submit for vetting.
  4. Select phone numbers for CNAM Registration.
    • Only those phone numbers already assigned to your Business Profile are eligible.
  5. Click Save
    • When the CNAM Trust Product reaches Twilio-Approved status, Twilio will register CNAM display name for your numbers with the CNAM authoritative databases in the United States.

NOTE: You can remove CNAM by unassigning Phone Number from CNAM Trust Product or by deleting the CNAM Trust Product.

That's it. No coding required.

CNAM Onboarding with the Trust Hub REST API

Please refer to Trust Hub Rest API Docs for more details.

1. Create a Business Profile in the Console's Trust Hub and submit for vetting.

2. Assign phone numbers in your account to the Business Profile. This associates a single identity with the phone numbers.

  • You'll need your Phone Number SID(s)
    • To find your Phone Number SIDs in the Console, go to your Dashboard. In the Project Info section, click on See all phone numbers, then click on a phone number to find the SID.
    • To find your Phone Number SIDs via API, see the Additional API Calls section below.
    • Phone Number SIDs begin with "PN".
    • In the API Call below, don't change the ChannelEndpointType. It needs to be phone-number to add a phone number to your Business Profile.
Loading Code Sample...
        
        

        Assign Phone Numbers to Your Business Profile

        3. Create CNAM Trust Product

        • Note: Do not change the policy_sid from the example below. This is a static value that will stay the same across all accounts.
        • The response will contain the SID for your Trust Product. You'll need this for several other API calls.
        Loading Code Sample...
              
              

              Create CNAM Trust Product

              4. Connect your CNAM Trust Product to your Business Profile

              Loading Code Sample...
                    
                    

                    Connect your CNAM Trust Product to your Business Profile

                    5. Create CNAM End User

                    • Note: In the API Call below, don't change the Type. It needs to be cnam_information to create the proper CNAM End User resource.
                    • This API call will return the SID for the End User. You will need this in the next step.
                    Loading Code Sample...
                          
                          

                          Create CNAM End User

                          6. Connect your CNAM Trust Product to your End User

                          • You will need the End User SID from the previous step.
                          • You will also need the CNAM Trust Product SID, returned from the API call in Step 3
                          Loading Code Sample...
                                
                                

                                Connect your CNAM Trust Product to your End User

                                7. Add Phone Number to CNAM Trust Product

                                • You'll need the CNAM Trust Product SID, returned from the API call in Step 3
                                • You'll need the Phone Number SID(s) you assigned to your Business Profile earlier. (Note: Only those phone numbers already assigned to your Business Profile are eligible)
                                • You'll need your Buisness Profile SID. It starts with "BU".
                                • To retrieve any of these SIDs via API, see the Additional API Calls section below.
                                • Note: Don't change the ChannelEndpointType
                                Loading Code Sample...
                                      
                                      

                                      Assign Phone Numbers to your CNAM Trust Product

                                      8. Submit CNAM Trust Product

                                      Loading Code Sample...
                                            
                                            

                                            Submit CNAM Trust Product for Vetting

                                            Additional Information

                                            Learn more about Business Profiles and other Trust Products in the Trust Hub Docs.

                                            After your CNAM Trust Product reaches "Twilio-Approved", the display name may take 48-72 hours to propagate to all carriers in the United States.

                                            Please note a CNAM display name only appears on devices if enabled by the subscriber and is dependent on the terminating carrier to display the proper registered CNAM.

                                            For landlines, CNAM is always enabled by default.

                                            For mobile devices most commonly, US Carriers require the subscriber to opt-in. If the recipient does not have the CNAM feature or app enabled on their phone no CNAM will display even if a CNAM is properly set for number.

                                            A specific carrier may have outdated CNAM information. For the CNAM to be displayed accurately, the recipient’s carrier must query the CNAM databases (LIDB) and update their records. If a carrier has not recently performed a query it may cause the recipient to see outdated CNAM information for the number.

                                            Additional API Calls

                                            Loading Code Sample...
                                                  
                                                  

                                                  Get Phone Number SIDs from Parent Account

                                                  Loading Code Sample...
                                                        
                                                        

                                                        Check Business Profile Phone Number Assignments

                                                        Loading Code Sample...
                                                              
                                                              

                                                              Get Business Profile SIDs

                                                              Loading Code Sample...
                                                                    
                                                                    

                                                                    Check Business Profile Phone Number Assignments

                                                                    Loading Code Sample...
                                                                          
                                                                          

                                                                          Fetch Trust Product SIDs

                                                                          Loading Code Sample...
                                                                                
                                                                                

                                                                                Check CNAM Phone Number Assignments

                                                                                Rate this page:

                                                                                Need some help?

                                                                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                                                                Thank you for your feedback!

                                                                                Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                                Sending your feedback...
                                                                                🎉 Thank you for your feedback!
                                                                                Something went wrong. Please try again.

                                                                                Thanks for your feedback!

                                                                                thanks-feedback-gif