How It Works
Understand the request lifecycle and how nXus bridges your application with QuickBooks Desktop.
How It Works
nXus is a real-time API bridge for QuickBooks Desktop. You send JSON, you get JSON back. Every request fetches live data directly from QuickBooks — nothing is cached, stored, or stale.
Architecture Overview
Architecture Overview
Modern API request in, live QuickBooks data back out
Your Application
Sends a standard API request and receives clean JSON back.
nXus Platform
Authenticates the call and converts JSON into QuickBooks-safe QBXML.
Accounting Environment
The Web Connector sends the request into the active company file for live processing.
Request Lifecycle
You Send a JSON Request
Your application makes a standard REST call to the nXus API — just like any modern API. Include your API key and your connection ID to target a specific QuickBooks company file.
GET /api/v1/Invoices
Authorization: Bearer sk_live_...
X-Connection-ID: your_connection_idnXus Translates to QBXML
nXus converts your JSON request into the QBXML format that QuickBooks Desktop requires. You never need to learn, write, or debug QBXML — nXus handles the entire translation, including field mapping, validation, and query construction.
QuickBooks Processes the Request
The nXus Connector, running alongside QuickBooks Desktop, securely delivers the translated request. QuickBooks processes it — querying records, creating invoices, updating customers, or whatever the operation requires.
nXus Translates the Response
QuickBooks returns its result in raw QBXML. nXus parses the response, normalizes the data into a clean, consistent JSON structure, and includes metadata like pagination cursors and request tracking IDs.
You Get JSON Back
The final JSON response is returned to your application. From your perspective, you made a REST call and got a REST response — the QuickBooks complexity is completely invisible.
Most requests complete in 1-3 seconds, depending on the operation and how responsive your QuickBooks Desktop instance is. The bottleneck is QuickBooks itself, not nXus.
Key Design Principles
Tenant Auth, Connection Scope
nXus uses a two-layer model:
- The tenant is your SaaS account or developer account. Authentication happens at this level with your API key.
- The connection is a specific end user or QuickBooks company file under that tenant.
That means most QuickBooks resource routes stay resource-first, like GET /api/v1/customers or GET /api/v1/invoices. The request is scoped to the correct company file by sending X-Connection-ID, rather than nesting every route under /connections/{connectionId}.
Use connectionId in the path or request body only when the connection itself is the resource being managed, such as connection management, auth sessions, or setup flows.
Always Fresh Data
Every API call fetches live data directly from QuickBooks Desktop. nXus does not cache or mirror your QuickBooks data. Even if two identical requests are made seconds apart, both trigger a fresh fetch — guaranteeing your application always sees the current state of your books.
Zero Data Persistence
Your QuickBooks data flows through nXus in-memory and is returned directly to your application. It is never written to a database, never stored on disk, and never persisted in any cache. The only data nXus stores is operational metadata — your account info, API keys, and request logs for debugging.
One API, Many Company Files
Each request is scoped to a specific QuickBooks company file via the X-Connection-ID header. You can connect multiple company files to the same nXus account and target each one independently with the same API key.
What about pagination?
For large datasets, nXus handles QuickBooks Desktop’s internal pagination system transparently. You simply follow the nextCursor from each response to retrieve the next page. See the Pagination guide for details.