> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Field mapping

Field mapping decides what data from your CRM lands on a Pivotal customer record. Pivotal ships with sensible defaults for the HubSpot company object, and the mapping page lets you add, remove, or rewire any field.

Open it at **Admin > Integrations > HubSpot > Field mapping**. The page shows two columns: the Pivotal field on the left, the HubSpot property feeding it on the right.

## The default map

| Pivotal field    | HubSpot property                            | Type      | Notes                                                                           |
| ---------------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------------- |
| `name`           | `Company name` (`name`)                     | string    | The customer's display name. Required, never blank.                             |
| `domain`         | `Company Domain Name` (`domain`)            | string    | Match key for Stripe and webhook routing. Lowercased on write.                  |
| `owner`          | `Hubspot Owner` (`hubspot_owner_id`)        | user      | Looked up by HubSpot owner email; falls back to the workspace admin if unknown. |
| `plan`           | `Tier` (`tier`)                             | enum      | Resolves against your Pivotal plan list. Case-insensitive.                      |
| `arr`            | `Annual Revenue` (`annualrevenue`)          | number    | Stored in USD. Convert before writing if you bill in another currency.          |
| `industry`       | `Industry` (`industry`)                     | string    | Free text. Shown on the customer header.                                        |
| `employee_count` | `Number of Employees` (`numberofemployees`) | number    | Used in the health-score size bucket.                                           |
| `created_at`     | `Create Date` (`createdate`)                | timestamp | Read-only after the first sync.                                                 |

## When a HubSpot property has no Pivotal equivalent

Three options, in order of preference:

1. **Create a custom field** on the Pivotal customer object at **Admin > Workspace > Custom fields**, then point the HubSpot property at it on the mapping page. Custom fields show up under **Details > More** on the customer page and are queryable from filters and Pi.
2. **Map to a tag**. If the HubSpot property is a boolean or single-value enum, map it to a Pivotal tag instead of a field. Tags are cheaper to render and easier to filter on. See [tags and metadata](/product/customers/tags-and-metadata).
3. **Drop it**. Unmapped HubSpot properties stay in HubSpot. Pivotal doesn't lose them; it just doesn't surface them. Drop fields you don't act on. Less noise on the customer page beats completeness.

## Rules for adding a custom mapping

A few constraints keep the mapping safe:

* Pivotal field types must match. You can't push a HubSpot string into a Pivotal number field; the row goes red.
* A Pivotal field can be fed by one HubSpot property at a time. To combine two HubSpot properties into one Pivotal field, use a [webhook](/product/integrations/webhooks) and write the combined value via the API.
* Read-only Pivotal fields (`id`, `display_id`, `created_at`) cannot be remapped.

## Gotcha: HubSpot multi-select properties

HubSpot multi-select properties send a semicolon-separated string (`"NA;EMEA;APAC"`). Map these to a Pivotal tag set rather than a string field. The mapping UI offers a **Split by ;** toggle that does this for you.

## Related

* [Connect HubSpot](/product/integrations/connect-hubspot)
* [Tags and metadata](/product/customers/tags-and-metadata)
* [Troubleshoot sync](/product/integrations/troubleshoot-sync)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.