Data Import Overview

What You Can Import

Adva’s data import system lets you bring in your existing business data from any source — spreadsheets, other software, or custom integrations. You can import via:

• CSV files — Upload spreadsheets through the web UI or API
• Batch JSON API — Send records programmatically for automated integrations

Both methods support the same 20 entity types, use the same validation rules, and produce the same results.

Supported Entity Types

Entities must be imported in tier order. Lower tiers must complete before higher tiers, because higher-tier entities reference lower-tier entities.

Tier 1: Products, Territories, Brands           (no dependencies)
   |
Tier 2: Customers, Team Members, Crews,         (may reference territories)
        Commission Plans, Promotions
   |
Tier 3: Deals, Locations, Brand Assignments      (reference customers, team members)
   |
Tier 4: Proposals, Proposal Items,               (reference deals, customers, products)
        Jobs, Job Items
   |
Tier 5: Invoices, Warranties,                    (reference jobs, customers, deals)
        Proposal Discounts
   |
Tier 6: Transactions, Commissions                (reference deals, invoices, team members)

Entities within the same tier can be imported in any order.

How Cross-Referencing Works

Every record can include an external_id — a unique identifier from your source system. This enables two things:

1. Idempotent imports — Re-importing the same file updates existing records instead of creating duplicates.
2. Cross-entity linking — Use *_external_id columns to connect records. For example, a proposal’s customer_external_id references the customer’s external_id.

External IDs can be any string: database primary keys, Airtable record IDs, row numbers, or custom identifiers. They must be unique per entity type within a single import source.

Example

Import customers first:

external_id	first_name	last_name
CUST-001	John	Smith
CUST-002	Sarah	Johnson

Then import deals referencing those customers:

external_id	customer_external_id	name	deal_type
DEAL-001	CUST-001	Smith Backyard	project
DEAL-002	CUST-002	Johnson Patio	project

Adva resolves CUST-001 to John Smith’s internal ID automatically.

Import Modes

Mode	Behavior
incremental	Creates new records and updates existing ones (matched by external_id). Default.
full	Same as incremental, plus flags records that exist in Adva but are missing from the import file as potentially deleted.

Authentication

Imports can be authenticated two ways:

Method	Use Case	How
API Key	IT admins, automated integrations	Create an API key in Adva, include it as X-API-Key header
JWT Token	Web UI users	Use your session token as a Bearer token

See Authentication for details on obtaining tokens.

Next Steps

• CSV Import Guide — Download templates and import data from spreadsheets
• API Import Guide — Import data programmatically with the batch JSON API