Integrations

Field mapping

Map HubSpot company properties to Pivotal customer fields, with rules for the leftovers.
View as Markdown

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 fieldHubSpot propertyTypeNotes
nameCompany name (name)stringThe customer’s display name. Required, never blank.
domainCompany Domain Name (domain)stringMatch key for Stripe and webhook routing. Lowercased on write.
ownerHubspot Owner (hubspot_owner_id)userLooked up by HubSpot owner email; falls back to the workspace admin if unknown.
planTier (tier)enumResolves against your Pivotal plan list. Case-insensitive.
arrAnnual Revenue (annualrevenue)numberStored in USD. Convert before writing if you bill in another currency.
industryIndustry (industry)stringFree text. Shown on the customer header.
employee_countNumber of Employees (numberofemployees)numberUsed in the health-score size bucket.
created_atCreate Date (createdate)timestampRead-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.
  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 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.

Email help@pivotal.app with a screenshot of where you got stuck and the customer or onboarding id from the URL.