Import
Settings → Import loads records you already keep in a spreadsheet. Download the template, fill it in, check it, then import. Nothing is saved until you press Import, and rows that are already here are skipped, never changed.
There are eight types: Patents, Patent filings, Trademarks, Domains, Contracts, Legal entities, Employees and Customer accounts.
How an import works #
- What are you importing? Pick the type. The card says which screen the records go to.
- The template. The table lists every column, whether it is required, what goes in it and an example. Press Download template to get a CSV with just the header row.
- Your file. Choose your filled-in CSV file and press Check file. This is a dry run: every row is validated and checked for duplicates, and nothing is written. The Check report shows Rows read, Ready to import, Errors and Already here, then each row with what happened.
- Import. Press Import N rows. The rows that passed are created in one step; rows with errors and duplicates are skipped. If any row fails to save, nothing is saved.
After an import, Open … takes you to the screen where the records now show, and Import another file starts again.
Template tips #
- Keep the header row exactly as downloaded. Headers are matched without regard to case, but every name must be one the template has.
- One record per row after the header. Blank lines are ignored.
- Don't leave the example values in: the template has no example row on purpose, because it would be imported.
- Dates are
YYYY-MM-DD, like2026-03-31. - True/false columns accept
trueorfalse(yes/noand1/0also work). - Brand columns take the brand's slug from Settings → Brands (lowercase letters, digits and dashes, like
northwind-coffee), not its display name. - Values that contain a comma must be in double quotes. Spreadsheet programs do this for you when they save as CSV.
- Save as CSV UTF-8. In Excel: File → Save As → CSV UTF-8.
- Up to 5,000 rows and 2 MB per file. Split larger files.
- Import parents before children: patents before their filings, and a parent entity or a manager before the rows that point at them (or earlier in the same file).
- Row numbers in the report are the file's line numbers (the header is row 1), as your spreadsheet shows them.
Who can import #
Each type needs its engine's admin role (or founder): patents admin, legal admin, HR admin or customer success admin. Brand-scoped admins can import rows for their own brands; rows for other brands come back as errors, one by one.
Common errors #
| Message | Fix |
|---|---|
| "The file is empty. It needs the template's header row and at least one data row." | Add your rows under the header. |
| "The file has a header row but no data rows." | Add at least one row. |
"Column … (header column …) isn't one the … import knows." | Fix or remove that column. The message lists the template's columns. |
| "The header is missing required column…" | Start from the downloaded template. |
| "This row has … cells but the header has …; a value is probably missing its quotes." | Put double quotes around values that contain commas. |
| "A quoted value starting on line … is never closed" | A " is missing. Fix that line. |
"… must be a date written YYYY-MM-DD (e.g. 2026-03-31); got …." | Reformat the date. Set the column's format to text in your spreadsheet if it keeps changing it. |
"… must be one of: …; got …." | Use one of the listed values. |
"… must be a brand slug: lowercase letters, digits and dashes (e.g. northwind-coffee); got …." | Use the slug, not the brand's name. |
"You don't have admin access to brand …, so this row can't be imported." | Ask for the admin role on that brand, or remove the row. |
| "This … is already recorded (same key), so this row is skipped." | Nothing to do: the record exists. Imports never change existing records. |
| "The file is … MB; the limit is 2 MB. Split it into smaller files." | Split the file. |
| "Row … now matches a record that was added after the check ran, so nothing was imported. Run the check again." | Press Check file again, then import. |
The columns, type by type #
Patents #
Template: vxt-import-patents.csv. Shows on the Patents screen. Needs patents admin. A re-import matches on internal_id (ignoring case). One row per invention. Import patents before their filings.
| Column | Required | What goes in it | Example |
|---|---|---|---|
internal_id | yes | Your own reference for the invention; unique. A re-import matches on it. | 26-13-10 |
title | yes | The invention's title. | Adaptive load shedding for edge gateways |
lifecycle_stage | yes | Where the invention stands. One of: drafted, briefed, writing, completed_unsubmitted, active, superseded, killed_consolidated, abandoned. | active |
short_description | no | One or two sentences. Optional. | Sheds load before the gateway saturates. |
group_code | no | Your grouping code (portfolio, family). Optional. | 26-13 |
domain | no | Technical domain, free text. Optional. | networking |
priority_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2026-04-01 |
parent_internal_id | no | internal_id of the parent invention: one that already exists or appears earlier in this file. Optional. | 26-13-01 |
brand | no | Attributes the patent to this brand (brand slug: lowercase letters, digits, dashes). Optional. | northwind-coffee |
Patent filings #
Template: vxt-import-filings.csv. Shows on the Patents screen. Needs patents admin. A re-import matches on serial_number (ignoring punctuation); without one, the patent + application type + filing date + label. Each filing belongs to a patent that must already exist: import patents first. The keep decision starts as pending, as on a hand-entered filing.
| Column | Required | What goes in it | Example |
|---|---|---|---|
patent_internal_id | yes | internal_id of an existing patent. | 26-13-10 |
application_type | yes | The kind of application. One of: provisional, nonprovisional, continuation, continuation_in_part, divisional, pct. | provisional |
status | yes | The filing's state. One of: provisional_filed_paid, provisional_filed_unpaid, lapsing_strategic, abandoned_strategic, abandoned_uspto_terminated, misfiled_pending_refile, superseded_by_refile, nonprovisional_filed, pct_filed, granted. | provisional_filed_paid |
serial_number | no | The USPTO application number. A re-import matches on it. Optional. | 64/024,054 |
filing_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2026-04-01 |
filing_label | no | A short label such as original or refile. Optional. | original |
conversion_deadline | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2027-04-01 |
uspto_correspondence_email | no | The correspondence email on file with the USPTO. Optional. | ip@northwind.example |
notes | no | Free text. Optional. |
Trademarks #
Template: vxt-import-trademarks.csv. Shows on the Legal screen. Needs legal admin for each row's brand (rows without a brand need company-wide legal admin). A re-import matches on mark_text (ignoring case), or uspto_serial when given.
| Column | Required | What goes in it | Example |
|---|---|---|---|
mark_text | yes | The mark as filed or to be filed; unique. A re-import matches on it. | NORTHWIND |
status | yes | Where the mark stands. One of: cleared_unfiled, filed_pending, registered, blocked, dead, unknown. | filed_pending |
brand | no | The brand's slug: lowercase letters, digits and dashes (e.g. northwind-coffee). Optional. | northwind-coffee |
uspto_serial | no | The 8-digit USPTO serial number. Optional. | 90123456 |
classes | no | Nice classes 1-45, separated by semicolons (e.g. 9;42 or IC 009;IC 042). Optional. | 9;42 |
blocking_serial | no | Serial number of a third-party mark that blocks this one. Optional. | |
priority_rank | no | A whole number; 1 is most important. Optional. | 1 |
recommended_action | no | Free text, e.g. file_teas_plus. Optional. | file_teas_plus |
filing_fee_usd_per_class | no | Whole US dollars per class. Optional. | 350 |
notes | no | Free text. Optional. |
Domains #
Template: vxt-import-domains.csv. Shows on the Legal screen. Needs legal admin for each row's brand (rows without a brand need company-wide legal admin). A re-import matches on domain_name (ignoring case).
| Column | Required | What goes in it | Example |
|---|---|---|---|
domain_name | yes | The domain, e.g. northwind.example. Stored lowercase; a re-import matches on it. | northwind.example |
brand | no | The brand's slug: lowercase letters, digits and dashes (e.g. northwind-coffee). Optional. | northwind-coffee |
registrar | no | Who the domain is registered with. Optional. | cloudflare |
expiration_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2027-06-30 |
dnssec_enabled | no | true or false (yes/no and 1/0 also work). Blank means unknown. | true |
transfer_locked | no | true or false (yes/no and 1/0 also work). Blank means unknown. | true |
is_canonical | no | true for the brand's main domain. Blank means false. | false |
notes | no | Free text. Optional. |
Contracts #
Template: vxt-import-contracts.csv. Shows on the Legal screen. Needs legal admin for each row's brand (rows without a brand need company-wide legal admin). A re-import matches on contract_type + counterparty_name (ignoring case) + effective_date + brand. A signed contract's signed time is set to the moment of import, as on a hand-entered contract.
| Column | Required | What goes in it | Example |
|---|---|---|---|
contract_type | yes | The kind of agreement. One of: msa, nda, customer_agreement, pla, pilot, employment, vendor, partnership, other. | msa |
counterparty_name | yes | The other party's legal name. | Acme Logistics LLC |
status | yes | Where the contract stands. One of: draft, executed, expired, terminated, superseded. | executed |
brand | no | The brand's slug: lowercase letters, digits and dashes (e.g. northwind-coffee). Optional. | northwind-coffee |
effective_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2026-01-15 |
expiration_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2027-01-14 |
is_signed | no | true or false (yes/no and 1/0 also work). Blank means false. | true |
is_paid | no | true or false (yes/no and 1/0 also work). Blank means false. | false |
file_path | no | Where the signed copy lives (a path or link). Optional. | |
notes | no | Free text. Optional. |
Legal entities #
Template: vxt-import-entities.csv. Shows on the Legal screen. Needs company-wide legal admin. A re-import matches on name (ignoring case).
| Column | Required | What goes in it | Example |
|---|---|---|---|
name | yes | The entity's legal name; unique. A re-import matches on it. | Northwind Trading Co. |
entity_type | yes | The kind of entity. One of: parent, c_corp, llc, dba, holding_company, foundation, sub_entity. | c_corp |
state_of_formation | no | e.g. Delaware. Optional. | Delaware |
formation_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2019-05-02 |
brand_assignment | no | The brand's slug: lowercase letters, digits and dashes (e.g. northwind-coffee). Optional. | northwind-coffee |
parent_entity_name | no | name of the parent entity: one that already exists or appears earlier in this file. Optional. | |
hq_address | no | Free text. Optional. | |
registered_agent_name | no | Free text. Optional. | |
is_reg_cf_issuer | no | true or false (yes/no and 1/0 also work). Blank means false. | false |
notes | no | Free text. Optional. |
Employees #
Template: vxt-import-employees.csv. Shows on the HR screen. Needs HR admin. A re-import matches on work_email (ignoring case). Imported employees start active. Leave principal_id blank for people who don't sign in to the terminal; it can be linked later.
| Column | Required | What goes in it | Example |
|---|---|---|---|
display_name | yes | The person's name as it should appear. | Dana Whitfield |
work_email | yes | Their work email; a re-import matches on it. | dana@northwind.example |
hierarchy_level | yes | command = company-wide, core = one brand, bridge = a team or location within a brand, node = an individual contributor. One of: command, core, bridge, node. | core |
brand_scope | no | The brand slug they work in. Required unless hierarchy_level is command. | northwind-coffee |
location_scope | no | Their team or location, e.g. denver-hq. Required for bridge and node. | |
department | no | Free text. Optional. | Operations |
job_title | no | Free text. Optional. | General Manager |
hire_date | no | A date written YYYY-MM-DD (e.g. 2026-03-31). Leave blank if unknown. | 2024-02-19 |
reports_to_email | no | work_email of their manager: an existing employee or one earlier in this file. Optional. | |
principal_id | no | Their VX Terminal user id (a UUID), if they sign in. Blank = not linked. |
Customer accounts #
Template: vxt-import-customer-accounts.csv. Shows on the Customer Success screen. Needs customer success admin for each row's brand. A re-import matches on brand + account_name (ignoring case). Each account is owned by a terminal user: principal_id when given, otherwise you.
| Column | Required | What goes in it | Example |
|---|---|---|---|
account_name | yes | The customer's name. | Bluebird Cafe Group |
brand | yes | The brand slug the customer buys from: lowercase letters, digits and dashes. | northwind-coffee |
status | no | Blank means prospect. One of: prospect, pilot, active, at_risk, churned. | active |
primary_contact_email | no | Optional. | ops@bluebird.example |
arr_usd | no | Annual recurring revenue in US dollars, e.g. 12000 or 12,000.50. Blank means 0. | 12000 |
started_at | no | When they became a customer: YYYY-MM-DD, or a full timestamp. Optional. | 2025-11-01 |
notes | no | Free text. Optional. | |
principal_id | no | The owning terminal user's id (a UUID). Blank = you. |