CSV Import Guide
Quick Start
Section titled “Quick Start”- Download the CSV template for the entity type you want to import
- Fill in your data following the format conventions below
- Upload the file through the Adva web UI or the batch API
Format Conventions
Section titled “Format Conventions”| Convention | Format | Example |
|---|---|---|
| Dates | ISO 8601: YYYY-MM-DD | 2026-03-15 |
| Times | 24-hour: HH:MM | 08:00 |
| Booleans | true / false | true |
| Currency | Plain number, no $ or commas | 1234.56 |
| Arrays (tags) | Pipe-delimited | vip|repeat|commercial |
| Empty cells | Treated as null / not provided | |
| Header row | Required, must use exact snake_case names |
CSV Templates
Section titled “CSV Templates”Download and fill in the template for each entity type you need to import. Import them in tier order.
Tier 1: Products
Section titled “Tier 1: Products”File: products.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s product ID | |
name | string | Yes | Product name | |
description | string | No | Product description | |
category | string | No | Product category | |
unit_price | number | No | Price per unit | |
unit_type | string | No | Unit of measure (sqft, lb, ea) | |
product_code | string | No | Internal product code / SKU | |
is_active | boolean | No | true, false (default: true) | Whether product is active |
Tier 1: Territories
Section titled “Tier 1: Territories”File: territories.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s territory ID |
name | string | Yes | Territory name |
region | string | No | Region or district |
Tier 1: Brands
Section titled “Tier 1: Brands”File: brands.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s brand ID | |
name | string | Yes | Brand name | |
channel_type | string | No | direct, reseller, franchise, marketplace, referral | Channel type |
is_active | boolean | No | true, false (default: true) | Whether brand is active |
Tier 2: Customers
Section titled “Tier 2: Customers”File: customers.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s customer ID | |
first_name | string | No | First name | |
last_name | string | No | Last name | |
email | string | No | Valid email format | Email address |
phone | string | No | Phone number | |
company_name | string | No | Company name (commercial) | |
lifecycle_status | string | No | lead, prospect, customer, former_customer, inactive (default: lead) | Customer lifecycle stage |
customer_type | string | No | residential, commercial | Customer type |
territory_external_id | string | No | References territory external_id | |
assigned_rep_external_id | string | No | References team member external_id | |
lead_source | string | No | How the lead was acquired | |
customer_number | string | No | Display customer number | |
notes | string | No | Free-text notes | |
tags | string | No | Pipe-delimited: tag1|tag2 | Tags for categorization |
Tier 2: Team Members
Section titled “Tier 2: Team Members”File: team_members.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s team member ID | |
email | string | Yes | Valid email format | Email address (must be unique) |
first_name | string | No | First name | |
last_name | string | No | Last name | |
phone | string | No | Phone number | |
role | string | Yes | admin, manager, sales_rep, production, finance | Team role |
commission_tier | string | No | Commission tier identifier | |
display_title | string | No | Display title (e.g., “Senior Rep”) | |
primary_territory_external_id | string | No | References territory external_id | |
headshot_url | string | No | Valid URL | Profile photo URL |
Tier 2: Crews
Section titled “Tier 2: Crews”File: crews.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s crew ID |
name | string | Yes | Crew name |
status | string | No | Crew status |
notes | string | No | Notes |
territory_external_id | string | No | References territory external_id |
primary_contact_external_id | string | No | References team member external_id |
Tier 3: Opportunities
Section titled “Tier 3: Opportunities”File: opportunities.csv
An opportunity is the primary unit of business — a residential or commercial project that links proposals, jobs, invoices, and commissions together.
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s opportunity ID | |
customer_external_id | string | No | References customer external_id | |
assigned_rep_external_id | string | No | References team member external_id | |
deal_number | string | No | Display opportunity number | |
name | string | No | Opportunity name / title | |
deal_type | string | No | project, service_call, service_agreement, order (default: project) | Opportunity type |
stage | string | No | lead, appointment, proposal, sold, in_progress, completed, closed_lost (default: lead) | Pipeline stage |
sub_status | string | No | Sub-status within stage | |
lead_date | date | No | YYYY-MM-DD | Date lead was created |
sold_date | date | No | YYYY-MM-DD | Date opportunity was sold |
completed_date | date | No | YYYY-MM-DD | Date opportunity was completed |
lead_source | string | No | Lead acquisition source | |
is_self_gen | boolean | No | true, false | Whether lead was self-generated |
Column-name note. The on-disk DB columns
deal_numberanddeal_typewere intentionally NOT renamed by migration20260424184344— only the table (core.deals→core.opportunities) and the FK columns (*.deal_id→*.opportunity_id) moved. CSV headers must match the actual column names.
Tier 3: Locations
Section titled “Tier 3: Locations”File: locations.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s location ID |
customer_external_id | string | No | References customer external_id |
street_line_1 | string | No | Street address line 1 |
street_line_2 | string | No | Street address line 2 |
city | string | No | City |
state | string | No | State / province |
postal_code | string | No | ZIP / postal code |
country | string | No | Country code (e.g., US) |
location_type | string | No | Location type (residential, commercial) |
notes | string | No | Notes |
Tier 4: Proposals
Section titled “Tier 4: Proposals”File: proposals.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s proposal ID | |
customer_external_id | string | Yes | References customer external_id | |
opportunity_external_id | string | No | References opportunity external_id | |
proposal_number | string | Yes | Display proposal number | |
project_type | string | No | Type of project | |
status | string | No | draft, sent, viewed, approved, rejected, expired (default: draft) | Proposal status |
submit_date | date | No | YYYY-MM-DD | Date sent to customer |
expires_date | date | No | YYYY-MM-DD | Expiration date |
final_price | number | No | Final proposal price | |
project_notes | string | No | Project notes |
Tier 4: Proposal Items
Section titled “Tier 4: Proposal Items”File: proposal_items.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s line item ID |
proposal_external_id | string | Yes | References proposal external_id |
product_external_id | string | No | References product external_id |
description | string | No | Line item description |
quantity | number | No | Quantity |
unit_price | number | No | Price per unit |
is_optional | boolean | No | true, false (default: false) |
is_selected | boolean | No | true, false (default: true) |
sort_order | number | No | Display order |
Tier 4: Jobs
Section titled “Tier 4: Jobs”File: jobs.csv
A job is a work order — the actual field work that gets scheduled and completed.
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s job ID | |
customer_external_id | string | Yes | References customer external_id | |
opportunity_external_id | string | No | References opportunity external_id | |
proposal_external_id | string | No | References proposal external_id | |
crew_external_id | string | No | References crew external_id | |
lead_tech_external_id | string | No | References team member external_id | |
job_number | string | Yes | Display job number | |
name | string | No | Job name | |
job_type | string | No | Type of job | |
status | string | No | pending, scheduled, in_progress, completed, cancelled (default: pending) | Job status |
scheduled_date | date | No | YYYY-MM-DD | Scheduled date |
scheduled_start_time | string | No | HH:MM | Start time |
scheduled_end_time | string | No | HH:MM | End time |
estimated_hours | number | No | Estimated hours | |
production_start_date | date | No | YYYY-MM-DD | Actual start date |
production_end_date | date | No | YYYY-MM-DD | Actual end date |
total_cost | number | No | Total cost | |
total_revenue | number | No | Total revenue |
Tier 4: Job Items
Section titled “Tier 4: Job Items”File: job_items.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s job item ID |
job_external_id | string | Yes | References job external_id |
product_external_id | string | No | References product external_id |
name | string | No | Item name |
description | string | No | Item description |
category | string | No | Item category |
quantity | number | No | Quantity (default: 1) |
unit_type | string | No | Unit of measure |
unit_cost | number | No | Cost per unit |
labor_unit_cost | number | No | Labor cost per unit |
unit_price | number | No | Price per unit |
sort_order | number | No | Display order |
notes | string | No | Notes |
Tier 5: Invoices
Section titled “Tier 5: Invoices”File: invoices.csv
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s invoice ID | |
customer_external_id | string | Yes | References customer external_id | |
opportunity_external_id | string | No | References opportunity external_id | |
job_external_id | string | No | References job external_id | |
invoice_number | string | Yes | Display invoice number | |
invoice_type | string | No | deposit, progress, final, service | Invoice type |
status | string | No | draft, sent, paid, partial, overdue, cancelled, refunded (default: draft) | Invoice status |
subtotal | number | No | Subtotal before tax | |
tax_amount | number | No | Tax amount | |
total_amount | number | No | Total including tax | |
issue_date | date | No | YYYY-MM-DD | Date issued |
due_date | date | No | YYYY-MM-DD | Payment due date |
discount | number | No | Discount amount | |
notes | string | No | Notes |
Tier 5: Warranties
Section titled “Tier 5: Warranties”File: warranties.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s warranty ID |
opportunity_external_id | string | No | References opportunity external_id |
job_external_id | string | No | References job external_id |
crew_external_id | string | No | References crew external_id |
customer_external_id | string | No | References customer external_id |
tech_external_id | string | No | References team member external_id |
proposal_external_id | string | No | References proposal external_id |
territory_external_id | string | No | References territory external_id |
warranty_status | string | No | Warranty status |
urgency | string | No | Urgency level |
project_type | string | No | Project type |
production_start | date | No | Production start date |
production_end | date | No | Production end date |
warranty_complete | date | No | Completion date |
initial_report | string | No | Initial warranty report |
Tier 6: Transactions
Section titled “Tier 6: Transactions”File: transactions.csv
| Column | Type | Required | Description |
|---|---|---|---|
external_id | string | No | Your system’s transaction ID |
opportunity_external_id | string | No | References opportunity external_id |
job_external_id | string | No | References job external_id |
employee_external_id | string | No | References team member external_id |
crew_external_id | string | No | References crew external_id |
warranty_external_id | string | No | References warranty external_id |
invoice_external_id | string | No | References invoice external_id |
territory_external_id | string | No | References territory external_id |
vendor_external_id | string | No | References customer external_id (vendor) |
transaction_date | date | No | Transaction date |
amount | number | No | Transaction amount |
transaction_type | string | No | Transaction type |
payment_type | string | No | Payment method |
expense_type | string | No | Expense category |
check_number | integer | No | Check number |
sales_tax | number | No | Sales tax amount |
vendor_invoice | string | No | Vendor invoice number |
notes | string | No | Notes |
review_status | string | No | Review status |
category | string | No | Category |
is_approved | boolean | No | true, false (default: false) |
Tier 6: Commissions
Section titled “Tier 6: Commissions”File: commissions.csv
Commissions are calculated per opportunity. Each record represents one team member’s commission on one opportunity.
| Column | Type | Required | Allowed Values | Description |
|---|---|---|---|---|
external_id | string | No | Your system’s commission ID | |
opportunity_external_id | string | Yes | References opportunity external_id | |
team_member_external_id | string | Yes | References team member external_id | |
base_amount | number | Yes | Base revenue amount | |
commission_rate | number | Yes | Commission rate (decimal, e.g., 0.25 = 25%) | |
commission_amount | number | Yes | Calculated commission in USD | |
bonus_amount | number | No | Additional bonus amount (default: 0) | |
status | string | No | pending, payable, paid, cancelled (default: pending) | Commission status |
pay_period_start | date | No | YYYY-MM-DD | Pay period start date |
pay_period_end | date | No | YYYY-MM-DD | Pay period end date |
paid_at | string | No | ISO 8601 datetime | Date/time commission was paid |
total_amount is automatically calculated as commission_amount + bonus_amount and cannot be set directly.
Industry Pack Fields
Section titled “Industry Pack Fields”If your business has an activated industry solution pack (e.g., turf & landscaping), additional fields are available in the specifications, capabilities, or details JSONB columns on certain entity types.
For CSV import, include these as a JSON string in the appropriate column. For example:
specifications"{""project_type"":""turf_installation"",""is_self_gen"":true}"Contact your Adva administrator for the full list of industry pack fields available for your business.