Phone Number Formatting Guide

Phone numbers are stored differently across every platform. HubSpot might have (555) 123-4567, Jobber expects +15551234567, and Pipedrive stores 555-123-4567. This guide shows you how to normalize phone data so it syncs cleanly.

The Problem

Without formatting, phone sync creates mismatches:

HubSpot:   (555) 123-4567
Jobber:    555.123.4567
Pipedrive: 5551234567

These are all the same number, but matching algorithms won't recognize them as identical. This leads to duplicate records, failed matches, and inconsistent data.

Available Phone Transforms

FluxCascade provides three phone transformations:

Recommendation: Use phone_e164 as your default. It's the most unambiguous format and works across international boundaries.

Step 1: Identify Phone Fields

Each platform stores phone data differently:

HubSpot

• phone — Primary phone
• mobilephone — Mobile number
• hs_additional_phones — Semicolon-separated list

Jobber

• phone — Primary phone (on Client)
• phones — Array of phone objects with type labels

Pipedrive

• phone — Array of phone objects (work, home, mobile, etc.)

Salesforce

• Phone — Primary phone
• MobilePhone — Mobile number
• HomePhone — Home number

Step 2: Configure Primary Phone Mapping

Start with the main phone field:

1. Go to your mapping's Field Pairs
2. Add a pair for the primary phone:
   • Source: phone
   • Target: phone
3. Set the Transform to phone_e164
4. Set Default Country to your country code (e.g., US, CA, GB)

Why Set a Default Country?

Numbers without a country code need context:

Input:  (555) 123-4567
        ↓ phone_e164 (default: US)
Output: +15551234567

Input:  (555) 123-4567
        ↓ phone_e164 (default: GB)
Output: +445551234567

The default country is only used when the input number doesn't already include a country code. Numbers like +44 20 7946 0958 are parsed correctly regardless of the default.

Step 3: Handle Multiple Phone Fields

Most contacts have more than one phone number. Map each field explicitly:

Primary + Mobile (HubSpot → Jobber)

Field Pair 1: Primary Phone

• Source: phone
• Target: phone
• Transform: phone_e164 (default: US)

Field Pair 2: Mobile Phone

• Source: mobilephone
• Target: mobile_phone
• Transform: phone_e164 (default: US)

Primary vs. Secondary

If the target system only accepts one phone field, choose a priority:

1. Use phone (primary) as the default mapping
2. Only fall back to mobilephone if primary is empty
3. Use the default_value transform to set a fallback

Step 4: Bidirectional Phone Sync

For bidirectional mappings, decide who owns the phone data:

Option A: CRM Owns Phones

• CRM → Field Service: phone_e164 transform
• Field Service → CRM: Phone field excluded or read-only
• Best when sales team manages contact info

Option B: Last Write Wins

• Both directions: phone_e164 transform
• Conflict resolution: Last Write Wins
• Best when both teams update phone numbers

Option C: Split by Type

• CRM owns office/work phone
• Field service owns mobile phone
• Each system is authoritative for its phone type

Handling Edge Cases

Extensions

Input:  (555) 123-4567 ext. 890
Output: +15551234567 (extension stripped)

If extensions matter, map them to a separate text field (e.g., phone_extension) since E.164 doesn't support extensions.

Invalid Numbers

When a phone number can't be parsed:

• The field is skipped for that record
• Other fields still sync normally
• An error is logged in the sync details

Common invalid formats:

• N/A, none, TBD
• Incomplete numbers: 555-12
• Text mixed in: call after 5pm: 555-1234

Check your sync logs for phone formatting errors and clean up source data as needed.

Toll-Free and Special Numbers

Input:  1-800-FLOWERS
Output: +18003569377  (letters converted to digits)

Input:  911
Output: (skipped — not a valid subscriber number)

Short codes and emergency numbers are not valid E.164 numbers and will be skipped.

International Numbers Already in Source

If your data already includes international numbers:

Input:  +44 20 7946 0958  (UK number)
Output: +442079460958     (E.164, country preserved)

The phone_e164 transform detects existing country codes and preserves them, regardless of the default country setting.

Platform-Specific Tips

HubSpot

HubSpot's phone field is freeform text — users enter anything. Apply phone_e164 on the HubSpot side of every mapping to normalize on the way out.

Jobber

Jobber's API accepts E.164 and national formats. Sending phone_e164 formatted numbers works reliably.

Pipedrive

Pipedrive stores phones as an array of objects:

[
  { "value": "+15551234567", "label": "work", "primary": true },
  { "value": "+15559876543", "label": "mobile", "primary": false }
]

FluxCascade extracts the primary phone for mapping. Use connection settings to configure which label maps to which field.

Troubleshooting

Phone Numbers Not Matching

Cause: Different formats preventing deduplication

Solution: Apply phone_e164 to the phone field in both directions before matching runs

Duplicate Records from Phone Mismatches

Cause: Matching uses phone as a secondary identifier, and format differences cause misses

Solution: Use email as the primary matching field (more reliable), phone as secondary

Country Code Doubled

Cause: Input already has +1 but default country adds another +1

Solution: The phone_e164 transform handles this automatically. If you see doubled codes like +1+15551234567, check that you're not applying the transform twice (chained transforms).

Empty Phone Fields After Sync

Cause: Source phone value was unparseable

Solution: Check sync error logs for the specific record. Common fix: clean up the source data

Best Practices

1. Always use phone_e164 — It's the universal format that works everywhere

2. Set the correct default country — Match your business's primary operating country

3. Map each phone type explicitly — Don't try to merge work and mobile into one field

4. Use email for matching, not phone — Phone formats cause too many false negatives for reliable matching

5. Audit before initial sync — Run a test sync and review phone formatting errors before going live

6. Clean source data gradually — Fix invalid numbers in the source system as you find them in error logs

Next Steps

• Field Transformations — All available transforms
• Address Mapping — Handle another tricky field type
• HubSpot + Jobber Guide — Full integration setup with phone mapping