How to prepare for phone number normalization in the Front API

  • 16 April 2024
  • 5 replies

Userlevel 5
Badge +8

On September 1st 2024, we will be introducing E.164 phone number normalization to the Front API to address issues caused by inconsistent phone number handles attached to contacts. Phone number handles for contacts in Front can be created via the API, the Front contacts manager, incoming messages in channels, CRM contact syncs, and CSV import of contacts. With so many different ways of creating contacts and storing phone numbers for those contacts, it’s important to normalize the data because the different input formats can lead to duplicate contacts and related search issues.


To prepare for this change, make sure your API requests are sending valid phone numbers with the country code included. Country codes must be preceded by a plus (+) sign. Read the “Potential impacts” section below for details.

If you experience any issues with phone number normalization, reach out to us and we can roll the feature back for your company instance to give you more time to address the change.



  • Easier Contact Management: By normalizing phone number handles, users will be able to search and merge contacts more effectively. Inconsistent normalization creates difficulties in contact management, such as not being able to effectively identify or merge contacts who have the same number stored in a slightly different way: 512-555-1337 versus +1 (512) 555 1337 versus 15125551337, etc. This leads to duplicate contacts in Front.
  • Improved Search Functionality: Normalizing phone number handles will enable users to search for contacts using various phone number formats. For example, searching for 650 123 4567 or (650)123 - 4567 should return the same contact with the normalized handle +16501234567.
  • Merge Functionality: The introduction of phone number normalization also includes the ability to merge existing duplicate contacts that currently would create a merge conflict. This allows users to consolidate multiple contacts with the same handle into a single contact, eliminating duplicates and improving contact management efficiency.


Potential impacts


Developers will have to prepare for the following potential impacts when phone number normalization is released:

  • Missing country code (BREAKING CHANGE): Requests to the inbound and outbound Channel API message endpoints and to the custom channel incoming messages endpoint will default phone numbers to +1 (USA) if they are missing a country code. Front recommends always sending a country code. You must send country codes preceded with a plus (+) sign (e.g. +1 for USA, +33 for France, etc.).

    Example: +852 is the country code for Hong Kong. A correct way of sending a Hong Kong phone number to the Front API would be +85291234567. If you simply send 85291234567 instead, the phone number for the contact will be normalized as +185291234567.

  • Make sure phone numbers are valid: If phone numbers for a contact are not valid for requests sent to the inbound and outbound Channel API message endpoints or to the custom channel incoming messages endpoints, those numbers will save as a null value instead of as an invalid phone number.

    Invalid phone number:
    If you send 000, the phone number for the contact will be null instead of 000.

    Invalid area code for a country:
    If you send +33 (415) 555-5555, the phone number for the contact will be null because 415 is not a valid area code for France.

    Missing digit or incorrect phone number length
    If you send (415)-123-456, the phone number for the contact will default to a US country code (because it is missing an explicit country code) and will be null because US phone numbers must contain seven digits after the country and area codes.

  • Duplicate contacts might be created on a one-time basis: Normalizing phone numbers for API requests might cause duplicate contacts to be created for existing contacts in existing conversations, but these contacts can be manually merged by Front users if they occur. The duplicate contacts would only impact existing conversations. New conversations created after the normalization date would not be impacted.
  • Custom channels might thread messages differently if thread_ref is not used: If you are receiving messages in a custom channel but not sending the thread_ref parameter, differences in contact handles before and after normalization might cause messages to thread into new conversations after the normalization date because Front threads by sender if the thread_ref is empty. The threading issues would only affect existing conversations. New conversations created after the normalization date would not be impacted.
  • The contacts endpoints might reject certain requests: If you create or update a contact with a phone number that cannot be normalized to the E.164 standard, Front will reject your API request whereas before it would have accepted a value that didn’t make sense for a phone number.
  • Ensure you are sending phone number handles for phone channels: If you are using the inbound and outbound Channel API message endpoints for channels configured with the phone type, make sure the handle you send in the sender object is a valid phone number. Incorrectly sending an email address for a phone channel, for example, can lead to issues when managing the contact.

5 replies

Userlevel 4
Badge +5

Data Normalization and Enhancement

@Javier - Developer Relations, I thought this might be a good opportunity to ask if Front has any  recommended “Data Normalization and Enhancement” integration partnerships.  We know we can access this type of functionality via our CRM, that integrates with Front, but wondered if Front has anything similar now or in the pipeline.


Userlevel 5
Badge +8

@JohnW We don’t have anything in the pipeline regarding integrations. I’d be curious if you had any specific partners in mind or whether other customers had specific needs in this area. It’s not something I’ve heard too often. But that being said, we do want to normalize data as much as possible within Front itself while connecting to the most common CRMs out there.

Userlevel 4
Badge +5

Some of the leading providers of “Data Hygiene” integrations, that offer API access to their products are:

We are actively on the hunt for solutions, that work with both Front & HubSpot, in our ongoing pursuit of Best Source Of Truth (BSOT) options/solutions, that provide seamless and low-overhead update options, across our customer-data-dependent software stack.

Badge +1

This looks like it will only be regarding saved contacts, correct? Will anything need to change in our teams email signature with the phone number?

Userlevel 5
Badge +8

Hi @c_kelly - you’re correct, you don’t need to change anything for Front signatures. This only relates to contacts as specified in the inbound and outbound Channel API message and the custom channel incoming messages endpoints.