Overview

Understanding how to map data from external systems to Quivly

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 → 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

Default mappings get you started immediately. Standard fields sync automatically with best practices baked in.

When to Customize Mappings

You Have Custom CRM Fields

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.

Field Names Don't Match

External field names differ from Quivly’s expected names.

Example: Salesforce uses AnnualRevenue, but Quivly expects annual_revenue.

Solution: Map AnnualRevenue → annual_revenue in the field mapping editor.

You Want to Exclude Fields

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.

---

Object-Level Mapping

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

Salesforce

External Object	Quivly Object
Accounts	Customers
Contacts	Contacts
Users	External Users
Opportunities	Opportunities
Products	Billing Products

HubSpot

External Object	Quivly Object
Companies	Customers
Contacts	Contacts
Owners	External Users
Deals	Opportunities

Stripe

External Object	Quivly Object
Customers	Customers
Products	Billing Products
Subscriptions	Subscriptions
Invoices	Invoices

Pylon

External Object	Quivly Object
Issues	Support Tickets

Call Recordings

Source	External Object	Quivly Object
Fireflies	Transcripts	Call Recordings
Fathom	Meetings	Call Recordings

Data Warehouses

BigQuery, Snowflake, Redshift, ClickHouse, PostgreSQL, and MySQL integrations map warehouse tables to the Product Usage object via usage mapping configurations rather than direct object mappings.

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

External Field (HubSpot)	Quivly Field	Notes
name	name	Company name
domain	domain	Used for cross-system matching
industry	industry	Direct mapping
numberofemployees	employee_count	Number field
annualrevenue	annual_revenue	Currency field
hubspot_owner_id	account_owner	Reference to User object
customer_tier (custom)	customer_tier (custom)	Custom field mapping

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.