The caller's number exists in HubSpot, but the lookup misses it because one system stored a local format and another supplied an international format. The integration creates another contact even though the person was already known.
Phone normalisation should support matching without erasing country context or pretending a number uniquely identifies a person.
Preserve the original value and its interpretation
Keep the caller-provided or carrier-provided number where it serves a defined purpose, alongside the parsed representation used for lookup. Record which country context was supplied or verified.
A parser can help interpret numbers, but it cannot establish ownership or make a shared office line personal. Treat a parsed result as structured contact data, not proof of identity.
| Input condition | Required handling |
|---|---|
| Explicit international format | Parse under the documented numbering rules |
| Local number with confirmed country | Apply that context deliberately |
| Missing country context | Ask or route uncertainty rather than guess |
| Extension present | Preserve it separately where supported |
Avoid stripping all punctuation and assuming the remaining digits are comparable worldwide.
Match using the CRM's supported search behaviour
Review HubSpot's CRM search documentation for the current capabilities and limitations. Test representative stored values in the actual integration version.
Decide whether you need to clean existing data, add an approved normalised field, or use a controlled lookup service. Changing search input alone may not repair inconsistently stored historical records.
Do not turn normalisation into automatic merging
Two contacts can share a company or household number. A single person can also have several legitimate numbers. An apparent match should follow the business's identity policy before records are changed.
The duplicate-contact article separates identity resolution from event deduplication. Phone formatting addresses only part of that problem.
For a fictional shared office line, the correct result may be a company-level enquiry or staff review rather than a guessed employee contact.
Test the formats your callers actually use
Use fictional numbers representing international prefixes, local formats, extensions, missing values, and invalid input. Add a shared number with two contact records.
Inspect the selected record and original evidence after each test. Test rejected and ambiguous cases too; creating a new contact should not be the default response to every lookup problem.
Phone-matching questions
Does a valid-looking number prove the caller owns it?
No. Parsing and identity verification are different tasks.
Should historical records be rewritten automatically?
Plan a separate reviewed data-cleanup operation with recovery and ownership.
What should a useful fixture contain?
Include stored value, incoming value, country context, and expected match in the integration acceptance pack.