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

Without field mappings, Quivly wouldn’t know how to interpret data from your integrations:

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

When you connect an integration, here’s what happens:
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
  • Any transformations or formatting rules
4

Data Syncs

On each sync cycle (typically hourly), 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 intelligent default mappings for common fields: HubSpot Example:
  • HubSpot Companies → Quivly Customers
    • name → name
    • domain → domain
    • num_employees → employee_count
    • industry → industry
    • hubspot_owner_id → account_owner
Stripe Example:
  • Stripe Customers → Quivly Customers
    • name → name
    • email → email
    • description → description
Why defaults are helpful:
  • Get started immediately without manual configuration
  • Standard fields sync automatically
  • Best practices baked in

​
When to Customize Mappings

You’ll need to customize mappings when:
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.
External field names differ from Quivly’s expected names.Example: Salesforce uses AnnualRevenue, but Quivly expects annual_revenue.Solution: Map AnnualRevenue → annual_revenue.
External data needs reformatting before it’s useful in Quivly.Example: Salesforce stores phone as “(555) 123-4567”, but you want “+1-555-123-4567”.Solution: Apply transformation rules in field mapping.
Some external fields are irrelevant or sensitive and shouldn’t sync.Example: Don’t sync HubSpot’s internal tracking properties.Solution: Unmap those fields so they don’t sync.
Different integrations have data for the same Quivly field, and you need to set priority.Example: Both HubSpot and Salesforce have “Annual Revenue” - which one wins?Solution: Set field mapping priority (primary vs. secondary sources).

​
Object-Level Mapping

Before mapping fields, you map object types from external systems to Quivly objects:

​
Common Object Mappings

External SystemExternal ObjectQuivly Object
HubSpotCompaniesCustomers
HubSpotContactsContacts
HubSpotDealsOpportunities
HubSpotTicketsSupport Tickets
SalesforceAccountsCustomers
SalesforceContactsContacts
SalesforceOpportunitiesOpportunities
SalesforceCasesSupport Tickets
StripeCustomersCustomers
StripeSubscriptionsSubscriptions
StripeInvoicesInvoices
PylonAccountsCustomers
PylonIssuesSupport Tickets
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:

​
Field Mapping Components

Each field mapping has three parts:
  1. External Field - The field from the integration (e.g., HubSpot’s industry property)
  2. Quivly Field - The destination field in Quivly (e.g., industry)
  3. Mapping Rules - Optional transformations, defaults, or conditions

​
Example Field Mapping: HubSpot Companies → Quivly Customers

External Field (HubSpot)Quivly FieldNotes
namenameCompany name
domaindomainUsed for cross-system matching
industryindustryDirect mapping
numberofemployeesemployee_countNumber field
annualrevenueannual_revenueCurrency field
hubspot_owner_idaccount_ownerReference to User object
hs_lead_statusstatusDropdown: maps “NEW” → “Prospect”, “CUSTOMER” → “Active”
customer_tier (custom)customer_tier (custom)Custom field mapping

​
Mapping Strategies

Different strategies for different integration scenarios:

​
Strategy 1: Direct Mapping (Most Common)

When to use: Field names and data types match between systems Example:
  • HubSpot industry → Quivly industry
  • Stripe description → Quivly description
Configuration: Simply select the matching fields in the mapping editor.

​
Strategy 2: Transformed Mapping

When to use: Data needs reformatting or conversion Examples:
  • Date format conversion: Salesforce “2024-01-15” → Quivly timestamp
  • Currency conversion: Stripe amount in cents (5000) → dollars ($50.00)
  • Boolean conversion: HubSpot “Yes”/“No” → Quivly true/false
  • Case conversion: Uppercase to title case
Configuration: Select transformation type in mapping rules.

​
Strategy 3: Calculated Mapping

When to use: Quivly field should be calculated from multiple external fields Examples:
  • full_name = first_name + ” ” + last_name
  • mrr = subscription_amount / billing_interval_months
Configuration: Define formula in mapping rules.

​
Strategy 4: Conditional Mapping

When to use: Mapping logic depends on external field values Examples:
  • If HubSpot lifecyclestage = “customer”, then Quivly status = “Active”
  • If Stripe subscription_status = “active”, then Quivly is_active = true
Configuration: Set up conditional rules in mapping editor.

​
Strategy 5: Multi-Source Mapping with Priority

When to use: Multiple integrations provide data for the same Quivly field Example:
  • Primary source: Salesforce AnnualRevenue → Quivly annual_revenue
  • Fallback source: HubSpot annualrevenue → Quivly annual_revenue (only if Salesforce value is empty)
Configuration: Set integration priority in settings.

​
Mapping Lifecycle

Field mappings are not set-it-and-forget-it. They evolve as your needs change:
When you first connect an integration:
  1. Review default mappings
  2. Add mappings for custom fields
  3. Test with a few sample records
  4. Activate sync
Timeline: 15-30 minutes per integration

​
Who Manages Field Mappings?

Typical Role: Admins or RevOps team members Why admins?
  • Requires understanding of both Quivly’s data model and external systems
  • Incorrect mappings can corrupt data or cause sync issues
  • Changes to mappings affect entire organization
CSM involvement:
  • CSMs can request new field mappings (“We need to track Customer Tier from HubSpot”)
  • CSMs should not directly modify mappings unless trained
Changing field mappings affects existing data. Test changes carefully and communicate to your team when mappings will change, as it may affect reports, health scores, or workflows.

​
Impact on Health Scores

Field mappings directly affect customer health scores: Revenue Category:
  • MRR from Stripe Subscriptions
  • Outstanding balance from Stripe Invoices
  • Renewal date from CRM Opportunities
Engagement Category:
  • Last call date from Fireflies
  • Contact interaction frequency from CRM
Support Category:
  • Ticket volume from Pylon
  • Average resolution time from support tickets
Usage Category:
  • Usage metrics from data warehouse queries
Market Signals Category:
  • Auto-enriched (not dependent on mappings)
If health scores seem inaccurate, check that the underlying fields are correctly mapped from your integrations. Missing or incorrectly mapped fields will cause health score calculation issues.

​
Next Steps

Mapping Workflow

Step-by-step guide to configuring field mappings

Best Practices

Field mapping strategies and common pitfalls to avoid

Cross-System Linking

How Quivly matches customers across different integrations

Custom Fields

Create custom fields to receive mapped data

​
Common Questions

No. Only map fields you actually want to use in Quivly. Mapping too many fields:
  • Increases sync time
  • Creates clutter in customer profiles
  • Can cause data quality issues if external data is messy
Best practice: Start with essential fields, add more as needed.
Existing data is updated on the next sync cycle based on the new mapping.Example:
  • Old mapping: HubSpot status → Quivly customer_status
  • New mapping: HubSpot lifecycle_stage → Quivly customer_status
  • Result: On next sync, customer_status will be overwritten with lifecycle_stage data
Important: Changing mappings can overwrite existing data. Export data first if needed.
Yes, but use sparingly. This is typically done for calculated fields.Example:
  • HubSpot createdate → Both Quivly created_date AND first_seen_date
Why it’s rare: Usually one-to-one mappings are clearest and easiest to maintain.
The mapping will fail and you’ll see errors in sync logs.What to do:
  1. Check sync logs to identify the missing field
  2. Remove the mapping or map to a different external field
  3. Decide if you want to keep historical data in Quivly or clear it
Yes! You can map external data to custom objects you’ve created.Example:
  • External system: Asana
  • External object: Projects
  • Quivly custom object: Implementation Projects
  • Map Asana project fields to your custom object fields
This requires API-based integration or CSV imports for most external systems.

​
Key Takeaways

Field mappings define how external system data flows into Quivly’s data model.
Default mappings handle standard fields automatically; custom mappings are needed for custom fields and unique requirements.
Map object types first (e.g., HubSpot Companies → Customers), then map individual fields.
Different mapping strategies exist: direct, transformed, calculated, conditional, and multi-source mappings.
Field mappings directly impact health scores, reports, and customer views - configure them carefully.