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