Docs · Import & Export

Account import & export

Read, receive, and export the full chart of accounts and underlying transactions as files. This page documents the file formats, canonical schema, mapping wizard, validation rules, and HTTP API.

Module status: MVP shipping. Three inbound formats (CSV, XLSX, JSON) and four outbound formats (CSV, XLSX, JSON, audit-ready PDF). Statement-of-account parsers (OFX, QIF, MT940), regulator formats (XBRL, SAF-T), and Vietnam e-invoice XML are on the roadmap.

1. Supported formats

Inbound (read & receive)

Format	Use	Notes
CSV (UTF-8)	Generic CoA, journal entries, transactions	Configurable delimiter; header row required
XLSX	Multi-sheet workbook (CoA + transactions in one file)	First non-empty sheet auto-detected
JSON	Programmatic import; full schema match	Strict-mode and lenient-mode parsers

Outbound (export)

Format	Use	Notes
CSV (UTF-8)	Spreadsheet downstream	One file per entity; zip if bundled
XLSX	Multi-sheet bundle: CoA, GL, Trial Balance, period summary	Audit-friendly
JSON	Programmatic re-import or downstream pipeline	Same schema as import
PDF	Audit-ready bundle: cover page + tables + metadata footer	Watermarked with workspace ID + timestamp

2. Canonical Account record

{
  "account_code": "string (unique within workspace)",
  "account_name": "string",
  "account_type": "asset | liability | equity | revenue | expense | contra",
  "parent_code": "string | null",
  "currency": "ISO 4217 string",
  "tax_code": "string | null",
  "is_active": true,
  "opening_balance": "decimal | null",
  "opening_balance_date": "ISO 8601 date | null",
  "external_ids": { "quickbooks_id": "...", "xero_id": "...", "vas_code": "..." },
  "metadata": { "source_system": "string", "imported_at": "ISO 8601" }
}

3. Canonical Transaction record

{
  "transaction_id": "string",
  "posting_date": "2026-04-30",
  "document_date": "2026-04-29",
  "currency": "VND",
  "exchange_rate": null,
  "description": "Office supplies April",
  "reference": "INV-2026-0488",
  "lines": [
    { "account_code": "642", "debit": "1500000", "credit": null, "tax_code": "VAT_10", "memo": null },
    { "account_code": "1331", "debit": "150000", "credit": null, "tax_code": null, "memo": null },
    { "account_code": "111", "debit": null,    "credit": "1650000", "tax_code": null, "memo": null }
  ],
  "attachments": ["..."],
  "source_system": "csv-import",
  "imported_at": "2026-04-30T08:12:00Z"
}

4. Built-in standards

VAS (Vietnamese Accounting Standard, Circular 200/2014/TT-BTC) — full chart code mapping
IFRS — type-level mapping
US GAAP — type-level mapping
Local GAAP — fallback

5. Validation rules

account_code unique within workspace
account_type ∈ allowed enum
parent_code resolves to existing code (or null)
currency valid ISO 4217
For transactions: sum(debits) == sum(credits) per transaction (tolerance 0.01)
posting_date ≤ today and ≥ workspace open date
Duplicate detection by (transaction_id, source_system) composite

6. Import workflow

Capture — upload via UI, email, mobile, account feed, API, or file import
Detect — file type, encoding, sheet structure auto-detected
Map — wizard maps source columns to canonical fields; mappings are reusable
Validate — schema and balance checks
Preview — first 100 rows with errors highlighted by row + column
Confirm — accept; staged into workspace as pending_review
Review — operator approves; record posts
Audit — file hash, uploader, mapping snapshot, validation result, approver, timestamp

7. HTTP API

POST /api/v1/accounts/import

curl -X POST https://aiaccountingloop.com/api/v1/accounts/import \
  -H "Authorization: Bearer $WORKSPACE_TOKEN" \
  -F "[email protected]" \
  -F "target=accounts" \
  -F "mode=preview"

Response:

{
  "import_id": "imp_2026_04_30_abc123",
  "status": "preview",
  "rows_total": 2487,
  "rows_valid": 2480,
  "rows_invalid": 7,
  "errors": [
    { "row": 142, "column": "currency", "code": "ERR_CURRENCY_INVALID", "message": "Unknown ISO code 'VNDD'" }
  ],
  "preview_url": "/app/accounts/import/imp_2026_04_30_abc123/preview"
}

GET /api/v1/accounts/export

curl "https://aiaccountingloop.com/api/v1/accounts/export?scope=workspace&period_start=2026-01-01&period_end=2026-03-31&format=xlsx&include=coa,transactions,trial_balance" \
  -H "Authorization: Bearer $WORKSPACE_TOKEN" \
  -o export-q1-2026.xlsx

Small exports return the binary directly with audit headers (X-Export-Hash, X-Export-Audit-Id). Large exports return a 202 Accepted with a poll_url and an export_id for async retrieval.

8. Error codes

Code	Meaning
`ERR_FILE_TOO_LARGE`	File exceeds 50 MB synchronous cap. Use signed-URL upload.
`ERR_FORMAT_UNSUPPORTED`	Extension or magic bytes not in supported list.
`ERR_HEADER_MISSING`	CSV/XLSX missing header row.
`ERR_CURRENCY_INVALID`	Currency value is not a valid ISO 4217 code.
`ERR_PARENT_CODE_UNRESOLVED`	parent_code references an account that is not present.
`ERR_BALANCE_MISMATCH`	Transaction debits ≠ credits (tolerance 0.01 exceeded).
`ERR_DUPLICATE_TRANSACTION`	(transaction_id, source_system) already present.

9. Security & audit

File size cap 50 MB synchronous; signed-URL upload for larger files
MIME and magic-byte verification — extension alone is not trusted
All imports and exports logged with actor, IP, user-agent, file hash
Tokens scoped to workspace; cross-workspace data leak is forbidden by the query layer
Export PDF watermark contains workspace ID + timestamp

10. Filing posture

This module does not auto-file with any tax authority. Output files are user-owned. Submission to authorities remains guided submission: the platform prepares the export package; a human submits or routes through an authorized e-tax provider.

Try the import shell → Try the export shell →