> For the complete documentation index, see [llms.txt](https://help.getmobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.getmobly.com/help-center/integrations/crm/address-formatting.md).

# Address formatting

CRMs are picky about how they receive address data. Some routing rules only match on the two-letter **state code** (`CA`, not `California`); some reports only work when country is an ISO code; and most CRMs want the address split into discrete fields (street, city, state, postal code, country) rather than one blob.

Mobly's address formatting settings let you shape what gets sent to each CRM — per integration, per field — without changing what's stored in Mobly.

## What this solves

The **Address** field on a captured lead is a single string ("123 Main St, San Francisco, CA 94103, USA"). Most CRMs want it broken apart into their own address fields, and many of them want state and country in a specific format.

If your CRM's lead routing keys on state code (`CA`) and Mobly sends `California`, the rule doesn't match and the lead sits unrouted. Address formatting is how you make Mobly's outbound match your CRM's shape.

Two things you can control:

1. **Address split** — parse the single Address string into street / city / state / postal code / country as separate mapped fields.
2. **State and country format** — pick whether state renders as **code** (`CA`), **name** (`California`), or **ISO 3166-2** (`US-CA`); and whether country renders as **ALPHA2** (`US`), **ALPHA3** (`USA`), or **name** (`United States`).

Both settings live on the CRM integration's **Mapping** tab.

## Configuring address split

On the Mapping tab, find the **Address** row and open its gear dropdown. Choose **Transformations** to open the settings dialog.

Toggle **Split into components** on. Five new mappable fields appear in the mapping table:

* **Street**
* **City**
* **State**
* **Postal code**
* **Country**

Each behaves like any other Mobly field — pick the CRM field on the right side that it should populate.

{% hint style="info" %}
**The single Address field still exists** — the split is on top of it. If a CRM field expects the full address string, leave it mapped to Address. If a CRM field expects a component, map the component.
{% endhint %}

## Configuring state format

Under the same **Address** gear dropdown → **Transformations**, pick the format for **State**:

| Format         | Example (California) | When to use                                                                                                                                      |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Code**       | `CA`                 | Most CRM routing rules key on the two-letter code. Salesforce State picklists usually expect codes too.                                          |
| **Name**       | `California`         | HubSpot's default State property accepts full names; some custom reporting fields expect the readable name.                                      |
| **ISO 3166-2** | `US-CA`              | Only when your CRM specifically requires the international-standard code (e.g., a global org running one field for all countries' subdivisions). |

## Configuring country format

Country supports:

| Format     | Example (United States) | When to use                                                                        |
| ---------- | ----------------------- | ---------------------------------------------------------------------------------- |
| **ALPHA2** | `US`                    | Two-letter ISO code. Common in enterprise CRMs and marketing automation platforms. |
| **ALPHA3** | `USA`                   | Three-letter ISO code. Less common but some finance/enterprise systems require it. |
| **Name**   | `United States`         | Human-readable. Default for most HubSpot properties.                               |

## Company address formatting

The same **State** and **Country** format settings are available for Company address fields, reachable from the gear dropdown on the **Company State** and **Company Country** rows in the mapping table.

Company address is already stored as discrete fields in Mobly (no split needed), so only the state/country format settings apply on the Company side.

## Check my data

Before you commit a format choice, click **Check my data** in the Transformations dialog. Mobly runs the transform across the leads currently in your org and shows what percentage will resolve to a value.

Typical coverage from a well-populated Address field:

| Component   | Typical resolution rate |
| ----------- | ----------------------- |
| Country     | \~90%                   |
| State       | \~78%                   |
| City        | \~77%                   |
| Street      | varies (see below)      |
| Postal code | varies (see below)      |

Street and postal code depend heavily on how leads were captured — if most of your Address values are location strings like `"San Francisco, CA, USA"` (common when enrichment fills the field from a company profile), there's no street number to extract. Business card OCR usually populates the full mailing address, so orgs with heavy card-scan volume see much higher street coverage.

## What happens when Mobly can't parse a component

**A component is left blank rather than being sent to your CRM with a guess.**

This is deliberate. A wrong state code silently misroutes a lead — worse than an empty field somebody can see and fix. Mobly only emits a component when it can confidently match a subdivision or postal pattern.

If a lot of leads are coming through with blanks, that's a signal to look at the source data (typically Persona.address quality) rather than the format setting. Your CSM can pull an audit if that's happening.

## Per-integration, per-field

Every setting on the Transformations dialog is scoped to a single **integration + field** pair. That means:

* HubSpot and Salesforce can have different state formats — set each to what its routing / property expects
* Lead address and Company address can have different formats — set each independently
* Changing HubSpot's State format doesn't touch Salesforce's

Nothing about stored Mobly data changes. The transform runs at sync time, on the way out to the CRM. If you change a setting, all future syncs use the new value; past syncs stay as they were sent.

## Best practices

* **Match your CRM's routing rules first.** If routing keys on `US-CA`, use ISO 3166-2. If routing keys on `CA`, use Code. Guessing wrong here is the most common source of "why isn't my routing firing?"
* **Run Check my data before changing production settings.** Especially on state — a low resolution rate means a lot of leads will land with blank state, which may be worse than the current name-based mapping.
* **Use Code for state on Salesforce, Name on HubSpot** as a starting point — this matches the default picklist / property behavior on each. Adjust if your instance has been customized.
* **Split before you change format.** If you turn on split without mapping the derived components, the CRM will still receive the full address in the Address field. The two settings compose.

## Related articles

* [Field mapping](/help-center/integrations/crm/field-mapping.md) — the underlying mapping tab this configures
* [Mobly fields reference](/help-center/integrations/mobly-fields-reference.md) — what data lives in each Mobly field
* [How data flows from Mobly to your CRM](/help-center/integrations/crm/how-data-flows.md)
* [Reconciliation](/help-center/integrations/crm/reconciliation.md) — where sync failures land