Quickstart Guide

The HeadlessCPA API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes. Use it to sync with QuickBooks and Xero, pull bank feeds, auto-categorize transactions, and export data for CPAs — all behind one API.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Developer Dashboard.

Create a Client

Register a business as a Client to begin providing services. We return a secure Portal URL for bank connection, KYC data collection, and document uploads — which you can iframe or redirect users to.

curl https://api.headlesscpa.com/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Corp",
    "entity_type": "llc",
    "services": ["bookkeeping", "tax"]
  }
  '

QuickBooks Sync

Connect a client's QuickBooks Online account for two-way sync. Auto-import chart of accounts, journal entries, and transaction history. Changes made by CPAs in QuickBooks are reflected automatically.

Xero Sync

Connect a client's Xero account for two-way sync. Import chart of accounts, invoices, and bank transactions. Keep Xero and HeadlessCPA in sync without manual data entry.

Bank Feeds

Pull read-only transaction data from 10,000+ financial institutions via our Plaid integration. Transactions are automatically categorized using ML. Use the Portal URL to let your users securely connect their bank accounts.

Returns a Plaid Link token. Your user completes the bank connection flow in your UI, then HeadlessCPA pulls transactions automatically.

Auto-Categorization

Transactions from bank feeds and ledger syncs are automatically categorized using ML. Categories map to standard QuickBooks/Xero chart of account codes. CPAs review outliers; most transactions flow through without manual intervention.

Returns transactions flagged for CPA review. Update categories via the CPA Workspace or programmatically:

CPA Export

Export financial data in formats CPAs and tax professionals expect. Generate QuickBooks-ready CSVs, Xero import files, or PDF report packages. Trigger exports programmatically or from the dashboard.

Supported formats: quickbooks_csv, xero_csv, pdf, json.

Retrieve Reports

Fetch prepared financial reports to power your native UI dashboards. Available directly via API for complete UI control. Reports include P&L, balance sheet, and cash flow statements.

Webhooks

Subscribe to events via webhooks to build reactive experiences in your own application. Receive real-time notifications when syncs complete, categorizations are reviewed, or exports are ready.

• books.closed — Triggered monthly when the CPA finalizes the ledger.
• quickbooks.synced — Triggered when a QuickBooks sync completes.
• xero.synced — Triggered when a Xero sync completes.
• transactions.categorized — Triggered when ML categorization finishes for a batch.
• tax.return_filed — Triggered when a tax return is successfully submitted.
• export.ready — Triggered when a CPA export file is ready for download.
• task.action_required — Triggered if the CPA needs a document from the user.