> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quivly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **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.
</Info>

***

## Why Field Mappings Matter

<CardGroup cols={2}>
  <Card title="Unify Data Sources" icon="layer-group">
    Map HubSpot Companies, Salesforce Accounts, and Stripe Customers all to Quivly's Customer object
  </Card>

  <Card title="Handle Custom Fields" icon="sliders">
    Map custom CRM properties or billing metadata to Quivly fields
  </Card>

  <Card title="Maintain Data Quality" icon="badge-check">
    Control which fields sync and how they're formatted
  </Card>

  <Card title="Enable Cross-System Matching" icon="link">
    Use mapped fields (like domain, email) to match customers across integrations
  </Card>
</CardGroup>

***

## How Field Mappings Work

<Steps>
  <Step title="Integration Connects">
    You authenticate with an external system (e.g., HubSpot) and grant Quivly access to read data.
  </Step>

  <Step title="Quivly Discovers Objects">
    Quivly discovers what object types are available in that system (e.g., HubSpot has Companies, Contacts, Deals, Tickets).
  </Step>

  <Step title="You Configure Mappings">
    For each external object type, you define:

    * Which Quivly object it maps to
    * Which external fields map to which Quivly fields
  </Step>

  <Step title="Data Syncs">
    On each sync cycle, Quivly pulls data from the external system and populates Quivly fields based on your mappings.
  </Step>

  <Step title="Data Appears in Quivly">
    Mapped data appears in customer profiles, lists, and dashboards - unified across all your integrations.
  </Step>
</Steps>

***

## 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 get you started immediately. Standard fields sync automatically with best practices baked in.

### When to Customize Mappings

<AccordionGroup>
  <Accordion title="You Have Custom CRM Fields" icon="sliders">
    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.
  </Accordion>

  <Accordion title="Field Names Don't Match" icon="not-equal">
    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.
  </Accordion>

  <Accordion title="You Want to Exclude Fields" icon="eye-slash">
    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.
  </Accordion>
</AccordionGroup>

***

## Object-Level Mapping

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

<Tabs>
  <Tab title="Salesforce">
    | External Object | Quivly Object |
    | - | - |
    | Accounts | Customers |
    | Contacts | Contacts |
    | Users | External Users |
    | Opportunities | Opportunities |
    | Products | Billing Products |
  </Tab>

  <Tab title="HubSpot">
    | External Object | Quivly Object |
    | - | - |
    | Companies | Customers |
    | Contacts | Contacts |
    | Owners | External Users |
    | Deals | Opportunities |
  </Tab>

  <Tab title="Stripe">
    | External Object | Quivly Object |
    | - | - |
    | Customers | Customers |
    | Products | Billing Products |
    | Subscriptions | Subscriptions |
    | Invoices | Invoices |
  </Tab>

  <Tab title="Pylon">
    | External Object | Quivly Object |
    | - | - |
    | Issues | Support Tickets |
  </Tab>

  <Tab title="Call Recordings">
    | Source | External Object | Quivly Object |
    | - | - | - |
    | Fireflies | Transcripts | Call Recordings |
    | Fathom | Meetings | Call Recordings |
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

<Info>
  **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).
</Info>

***

## 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` | `customer_name` | Company name |
| `domain` | `domain` | Used for cross-system matching |
| `industry` | `industry` | Direct mapping |
| `numberofemployees` | `employee_count` | Number field |
| `annualrevenue` | `annual_revenue_usd` | Currency field |
| `hubspot_owner_id` | `csm_owner_id` | Reference to User object |
| `customer_tier` (custom) | `customer_tier` (custom) | Custom field mapping |

<Tip>
  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.
</Tip>

<Warning>
  Core field mappings may be **locked** for certain integrations to prevent accidental changes. Custom field mappings can always be added or modified.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.