Skip to content
Vespy API

Exporting to QuickBooks Online

The QuickBooks Online integration is a one-way export: Vespy pushes its accounting transactions into QBO. Nothing flows back, and QBO is never the source of truth for a Vespy record.

connect ──> map accounts ──> export ──> review records

1. Connect

Section titled “1. Connect”
Terminal window
curl -X POST https://api.getvespy.com/api/integrations/qbo/connect \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{ "redirectUrl": "https://appcenter.intuit.com/connect/oauth2?..." }

Send the user to redirectUrl. They authorize in Intuit’s UI, and Intuit redirects back to /api/integrations/qbo/oauth-callback, which stores the connection and bounces the browser to your app. Those callback endpoints are browser-facing — never call them directly.

Confirm the result with GET /api/integrations, or with the connected field on the export status endpoint below.

2. Map the chart of accounts

Section titled “2. Map the chart of accounts”

Vespy categories must be paired with QBO accounts before anything can export. Read both sides:

Terminal window
curl https://api.getvespy.com/api/integrations/qbo/accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN"


curl https://api.getvespy.com/api/integrations/qbo/mappings \
  -H "Authorization: Bearer $ACCESS_TOKEN"

For a fresh connection, let Vespy do the obvious pairings first:

Terminal window
curl -X POST https://api.getvespy.com/api/integrations/qbo/mappings/auto \
  -H "Authorization: Bearer $ACCESS_TOKEN"

This creates and saves mappings for the accounts it can match confidently. Then set the remainder with PUT /api/integrations/qbo/mappings, which replaces the whole mapping set — send the complete list, not a delta.

GET /api/integrations/qbo/export/status reports requiredMappings, each with a mapped flag. Every one must be true before an export will run.

3. Export

Section titled “3. Export”
Terminal window
curl -X POST https://api.getvespy.com/api/integrations/qbo/export \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"fromDate":"2026-09-01","toDate":"2026-09-30"}'

Both dates are YYYY-MM-DD and both are optional — omit them to export everything not yet exported. The call queues the work and returns immediately.

4. Watch it

Section titled “4. Watch it”
Terminal window
curl https://api.getvespy.com/api/integrations/qbo/export/status \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "connected": true,
  "exportFromDate": "2026-09-01",
  "exportToDate": "2026-09-30",
  "recordCounts": { "pending": 0, "synced": 214, "failed": 2, "skipped": 6, "conflict": 1 },
  "lastRun": {}
}

Then drill into the individual transactions:

Terminal window
curl "https://api.getvespy.com/api/integrations/qbo/export/records?status=conflict" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Record status Meaning
pending Queued, not yet sent
synced Accepted by QuickBooks
failed QuickBooks rejected it — the reason is on the record
skipped Deliberately not exported, for example a voided transaction
conflict The matching QuickBooks record changed since Vespy last saw it

Conflicts

Section titled “Conflicts”

conflict is the status worth paying attention to. It means someone edited the transaction in QuickBooks after Vespy exported it, so overwriting would silently discard their edit. Vespy stops instead of choosing for you.

Resolve it in QuickBooks — accept their version or restore Vespy’s — and re-export. Since the export is one-way, a conflict is always a signal that QBO is being edited directly, which is worth correcting at the source.