Get formatted phone numbers via API

[baernhardj]

Hi

I would like to get nice formatted phone numbers via HubSpot API.

My goal is to update the phone numbers in an external system. All phone numbers should look like the phone numbers in the HubSpot User Interface. I know the phone numers has different formats for the different countriers.

For example:

If the user enters '+41613456789' HubSpot shows '+41 61 345 67 89' (added some spaces).

If the user saves the number with spaces, HubSpot saves the spaces. If it is an US phone number, some other characters are added for the UI.

If I use the phone number validation in the property definition or as part of a workflow, the phone numer is stored without spaces or other special characters.

Is there a posibility to get the nice formatted phone numbers via API to show the phone numer in an external system?

[RubenBurdin · Accepted solution]

Hey @baernhardj   good question

there’s no API that returns the same “pretty” UI formatting. HubSpot stores the raw string you saved, and the UI applies presentation formatting on the fly. So the CRM API will give you what’s in the property, not the spaced version you see in-app.

Practical workaround inside HubSpot: use the new “Validate and format phone number” workflow action to normalize numbers, then write the formatted output back into a dedicated custom property like phone_formatted.

Your external system can read that property via API. HubSpot’s guide walks the steps and notes you must add a follow-up “Edit record” action to persist the parsed output

(https://knowledge.hubspot.com/workflows/format-phone-numbers-using-workflows )

Pair this with property validation so future entries arrive consistent. Turn on phone number validation and set a default country code if needed. This reduces messy inputs and keeps the formatted output stable for export

(https://knowledge.hubspot.com/properties/phone-number-property-validation )

If you prefer to keep storage in E.164 and only render “nice” strings downstream, format at the edge. Many teams read phone or mobilephone via the API, run libphonenumber in their service, and display locale-aware spacing in the external app. HubSpot’s property rules article explains where automatic formatting applies vs stored values, so you don’t rely on the UI’s spacing

(https://knowledge.hubspot.com/properties/automatic-formatting-for-property-rules )

Edge cases to mind: extensions, multiple numbers per record, and inconsistent country codes. Decide one canonical store (usually E.164) and keep a separate display property if your users must see local spacing. I’m inferring you’re on Enterprise with Workflows, correct me if not.

When teams sync CRMs and ops tools, they often keep both a canonical E.164 and a display-formatted field in the sync. A platform like Stacksync can keep those two properties in real time across systems so dialers get clean numbers while UIs stay human-friendly.

Hope this helps.

[RubenBurdin · Accepted solution]

Hey @baernhardj   good question

there’s no API that returns the same “pretty” UI formatting. HubSpot stores the raw string you saved, and the UI applies presentation formatting on the fly. So the CRM API will give you what’s in the property, not the spaced version you see in-app.

Practical workaround inside HubSpot: use the new “Validate and format phone number” workflow action to normalize numbers, then write the formatted output back into a dedicated custom property like phone_formatted.

Your external system can read that property via API. HubSpot’s guide walks the steps and notes you must add a follow-up “Edit record” action to persist the parsed output

(https://knowledge.hubspot.com/workflows/format-phone-numbers-using-workflows )

Pair this with property validation so future entries arrive consistent. Turn on phone number validation and set a default country code if needed. This reduces messy inputs and keeps the formatted output stable for export

(https://knowledge.hubspot.com/properties/phone-number-property-validation )

If you prefer to keep storage in E.164 and only render “nice” strings downstream, format at the edge. Many teams read phone or mobilephone via the API, run libphonenumber in their service, and display locale-aware spacing in the external app. HubSpot’s property rules article explains where automatic formatting applies vs stored values, so you don’t rely on the UI’s spacing

(https://knowledge.hubspot.com/properties/automatic-formatting-for-property-rules )

Edge cases to mind: extensions, multiple numbers per record, and inconsistent country codes. Decide one canonical store (usually E.164) and keep a separate display property if your users must see local spacing. I’m inferring you’re on Enterprise with Workflows, correct me if not.

When teams sync CRMs and ops tools, they often keep both a canonical E.164 and a display-formatted field in the sync. A platform like Stacksync can keep those two properties in real time across systems so dialers get clean numbers while UIs stay human-friendly.

Hope this helps.

[baernhardj]

Hi @RubenBurdin 

Thanks for the reply.

Our licence includes workflows. That is correct.

The validate on saving new phone numbers and the workflow to reformat the existing phone numbers: I tried both in a test environment. This works fine and the nubers are saved in standard format. That is excellent.

But I hoped, that there is a easier way to get a nice formatted number without coding it myself (also if most of the work is done by a library). 

The idea of field duplication for a formatted phone number will work but if you have 3 to 4 numbers for contacts and companies, it will be al lot of overhead.

I think the best way will be, to apply the formatting in the export function / process with the library. The export process is our own routine, so we have total control over the code.

Thanks a lot for the help.

Best regards

Bernhard

[BérangèreL · Accepted solution]

Hi @baernhardj, thanks for getting back to us!

And thanks @RubenBurdin for the help!

@baernhardj, I'd recommend that you share this feedback via the HubSpot Developer feedback form, so that it gets routed to the right Product Team and will get more visibility.

Thanks for your valuable feedback and have a lovely day!

Bérangère

[BérangèreL]

Hi @baernhardj, I hope that you are well!

Thanks for asking the HubSpot Community!

I'd love to put you in touch with our Top Experts and Community Members: Hi @GIlievski, @LMeert, @Anton and @reapandsow do you have suggestions to help @baernhardj, please?

Have a great day and thanks so much in advance for your valuable contributions!
Bérangère