Skip to main content

​
What are Field Mappings?

Field mappings define how data from external systems (like Salesforce, HubSpot, Stripe, Pylon) maps to Quivly’s data model. When integrations sync data, field mappings tell Quivly which external fields should populate which Quivly fields.
Think of field mappings as translation rules between external systems and Quivly. They ensure data from different sources flows into the right places in your unified customer view.

​
Why Field Mappings Matter

Unify Data Sources

Map HubSpot Companies, Salesforce Accounts, and Stripe Customers all to Quivly’s Customer object

Handle Custom Fields

Map custom CRM properties or billing metadata to Quivly fields

Maintain Data Quality

Control which fields sync and how they’re formatted

Enable Cross-System Matching

Use mapped fields (like domain, email) to match customers across integrations

​
How Field Mappings Work

1

Integration Connects

You authenticate with an external system (e.g., HubSpot) and grant Quivly access to read data.
2

Quivly Discovers Objects

Quivly discovers what object types are available in that system (e.g., HubSpot has Companies, Contacts, Deals, Tickets).
3

You Configure Mappings

For each external object type, you define:
  • Which Quivly object it maps to
  • Which external fields map to which Quivly fields
4

Data Syncs

On each sync cycle, Quivly pulls data from the external system and populates Quivly fields based on your mappings.
5

Data Appears in Quivly

Mapped data appears in customer profiles, lists, and dashboards - unified across all your integrations.

​
Default Mappings vs. Custom Mappings

​
Default Mappings

When you first connect an integration, Quivly provides default mappings for common fields: HubSpot Example:
  • HubSpot Companies → Quivly Customers
    • name → customer_name
    • domain → customer_domain
    • num_employees → employee_count
    • industry → industry
    • hubspot_owner_id → csm_owner_id
Stripe Example:
  • Stripe Customers → Quivly Customers
    • name → name
    • email → email
    • description → description
Default mappings provide a starting point. Review and save the required object mappings before relying on imported records. Monaco and Octolane also require an explicit account import scope during initial setup.

​
When to Customize Mappings

Your Salesforce or HubSpot has custom properties (e.g., “Customer Tier”, “Implementation Status”) that you want in Quivly.Solution: Map those custom external fields to Quivly custom fields. You can create new custom fields inline during mapping.
External field names differ from Quivly’s expected names.Example: Salesforce uses AnnualRevenue, but Quivly expects annual_revenue_usd.Solution: Map AnnualRevenue → annual_revenue_usd in the field mapping editor.
Some external fields are irrelevant or sensitive and shouldn’t sync.Example: Don’t sync HubSpot’s internal tracking properties.Solution: Leave those fields unmapped so they don’t sync.

​
Which CRM accounts are imported?

Field mappings decide which values populate a record. CRM import scope decides which source accounts become customers in Quivly. Supported CRMs can import all accounts or use reviewed conditions, such as a customer-status field or a related won opportunity. Account conditions and any opportunity conditions must match together; missing relationship evidence can delay qualification. Import scope is configured through Quivly-assisted onboarding. Contact your Quivly team to review or change it. The Data → Objects field mapping editor does not expose import-filter controls, and ordinary mapping saves preserve the existing scope. Changing an import filter does not delete customers already in Quivly. Previously filtered records can be reconsidered when the rule or relevant source evidence changes. If an expected account is missing, check its eligibility, object mappings, and source logs before assuming the connection failed.

​
Object-Level Mapping

Before mapping fields, you map object types from external systems to Quivly objects:
One external object can only map to one Quivly object, but multiple external object types can map to the same Quivly object (e.g., HubSpot Companies and Salesforce Accounts both map to Customers).

​
Field-Level Mapping

Once object types are mapped, you map individual fields. Each mapping connects an external field to a Quivly field.

​
Example: HubSpot Companies → Quivly Customers

Some fields are auto-computed by Quivly during sync (e.g., deriving a customer domain from an email address, or calculating opportunity status from CRM boolean fields). These appear as read-only in the mapping editor.
Core field mappings may be locked for certain integrations to prevent accidental changes. Custom field mappings can always be added or modified.