How It Works

Understand the request lifecycle and how nXus bridges your application with QuickBooks Desktop.

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

Modern API request in, live QuickBooks data back out

No caching or data persistence

REST client

JSON request

Your Application

Sends a standard API request and receives clean JSON back.

JSON in / JSON out

Translation layer

Translation + routing

nXus Platform

Authenticates the call and converts JSON into QuickBooks-safe QBXML.

API + translation

QuickBooks Desktop

Live QuickBooks processing

Accounting Environment

The Web Connector sends the request into the active company file for live processing.

QWC + company file

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.

bash

GET /api/v1/Invoices
Authorization: Bearer sk_live_...
X-Connection-ID: your_connection_id

nXus 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. Follow-up requests during an active session can drop to ~0.5 seconds. See the Latency Model for details on cold, active, and warm connection states.

Key Design Principles

nXus uses a two-layer identification model:

Authentication: Your API Key identifies your account and authorizes the request. Provide it as a Bearer token in the Authorization header or via the X-API-Key header.
Context: A Connection represents a specific QuickBooks company file. Every resource request must include an X-Connection-ID header to scope the action to the correct company. This approach keeps resource routes clean and “flat” (e.g., GET /api/v1/customers or GET /api/v1/invoices). You only use the connectionId in the URL path when managing the connection itself, such as during setup flows or session management.

Live Data, No Caching

Every API call retrieves live data directly from QuickBooks Desktop. nXus does not cache or mirror your data. Even if you make duplicate requests seconds apart, both trigger a fresh fetch—ensuring your application always reflects the current state of the 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, stored on disk, or persisted in a cache. nXus only stores minimal operational metadata, such as your account settings, API keys, and request logs for troubleshooting.

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.

API Keys Web Connector Setup