LedgerWire

Documentation

LedgerWire API

A JSON REST API over QuickBooks Desktop. Sandbox keys hit a hosted simulated company; live keys reach real company files through Intuit’s QuickBooks Web Connector. Base URL: https://ledgerwire.vibiz.app/v1

On this page

Quickstart

  1. Create a free account. You get a sandbox key (lw_test_…) and a seeded company file.
  2. Call any resource with the key as a Bearer token. No key yet? Use the read-only public demo key lw_test_demo_public_sandbox.
  3. When a customer is ready, create a connection, send them the setup page, and switch to a lw_live_… key.
first call
curl "https://ledgerwire.vibiz.app/v1/invoices?limit=1&status=unpaid" \
  -H "Authorization: Bearer lw_test_demo_public_sandbox"

Authentication

Send Authorization: Bearer <key>. The key decides the mode: lw_test_ keys only ever touch your sandbox; lw_live_ keys queue requests for a production connection. With several connections, name one with the LedgerWire-Connection: conn_… header. Responses carry LedgerWire-Mode (sandbox or production) and LedgerWire-Request-Id.

JSON conventions

JSON keys are the camelCase form of qbXML element names, so everything you know from the SDK carries over: CompanyName → companyName, BillAddress/Addr1 → billAddress.addr1. Ids: ListID, TxnID and TxnLineID become id; TimeCreated/TimeModified become createdAt/updatedAt. Refs stay refs: customerRef: { id, fullName }; send either field. Amounts are numbers.

Lists return { object: "list", data, hasMore, nextCursor }. Pass cursor=nextCursor for the next page; results are ordered by updatedAt, which makes updatedAfter incremental syncs simple.

Updates use QuickBooks optimistic locking: POST /v1/{resource}/{id} with the current editSequence. Only fields you send change. For transactions, send the full lines array (existing lines with their id, new lines without).

Resources

  • GET/v1/customers
  • GET/v1/customers/{id}
  • POST/v1/customers
  • POST/v1/customers/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, nameContains, nameStartsWith, status (active | inactive | all), ids.

Required on create: name. qbXML: Customer Query, Add, Mod.

POST /v1/customers
{
  "name": "Bayside Builders LLC",
  "companyName": "Bayside Builders LLC",
  "firstName": "Maria",
  "lastName": "Alvarez",
  "billAddress": {
    "addr1": "410 Harbor Way",
    "city": "Columbus",
    "state": "OH",
    "postalCode": "43215"
  },
  "phone": "(614) 555-0142",
  "email": "maria@bayside.example"
}
  • GET/v1/vendors
  • GET/v1/vendors/{id}
  • POST/v1/vendors
  • POST/v1/vendors/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, nameContains, nameStartsWith, status (active | inactive | all), ids.

Required on create: name. qbXML: Vendor Query, Add, Mod.

POST /v1/vendors
{
  "name": "Allied Pipe & Valve",
  "companyName": "Allied Pipe & Valve",
  "vendorAddress": {
    "addr1": "22 Industrial Pkwy",
    "city": "Tulsa",
    "state": "OK",
    "postalCode": "74103"
  },
  "phone": "(918) 555-0199",
  "nameOnCheck": "Allied Pipe & Valve"
}
  • GET/v1/items
  • GET/v1/items/{id}
  • POST/v1/items
  • POST/v1/items/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, nameContains, nameStartsWith, status (active | inactive | all), ids, type (service | inventory | nonInventory).

Required on create: name, type. qbXML: ItemService / ItemInventory / ItemNonInventory Query, Add, Mod.

POST /v1/items
{
  "type": "service",
  "name": "Site Survey",
  "salesOrPurchase": {
    "desc": "Pre-install site survey",
    "price": 180,
    "accountRef": {
      "fullName": "Service Income"
    }
  }
}
  • GET/v1/invoices
  • GET/v1/invoices/{id}
  • POST/v1/invoices
  • POST/v1/invoices/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, customerId / vendorId, refNumber, status (paid | unpaid | all, invoices and bills), ids.

Required on create: customerRef. qbXML: Invoice Query, Add, Mod.

POST /v1/invoices
{
  "customerRef": {
    "fullName": "Bayside Builders LLC"
  },
  "txnDate": "2026-11-09",
  "refNumber": "1201",
  "memo": "October service",
  "lines": [
    {
      "itemRef": {
        "fullName": "Installation"
      },
      "quantity": 6,
      "rate": 95
    },
    {
      "itemRef": {
        "fullName": "Thermostat T6"
      },
      "quantity": 2,
      "rate": 129
    }
  ]
}
  • GET/v1/sales-receipts
  • GET/v1/sales-receipts/{id}
  • POST/v1/sales-receipts
  • POST/v1/sales-receipts/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, customerId / vendorId, refNumber, status (paid | unpaid | all, invoices and bills), ids.

Required on create: lines. qbXML: SalesReceipt Query, Add, Mod.

POST /v1/sales-receipts
{
  "customerRef": {
    "fullName": "Bayside Builders LLC"
  },
  "txnDate": "2026-11-09",
  "refNumber": "SR-3001",
  "paymentMethodRef": {
    "fullName": "Visa"
  },
  "lines": [
    {
      "itemRef": {
        "fullName": "Air Filter 16x25"
      },
      "quantity": 4,
      "rate": 14.5
    }
  ]
}
  • GET/v1/receive-payments
  • GET/v1/receive-payments/{id}
  • POST/v1/receive-payments
  • POST/v1/receive-payments/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, customerId / vendorId, refNumber, status (paid | unpaid | all, invoices and bills), ids.

Required on create: customerRef, totalAmount. qbXML: ReceivePayment Query, Add, Mod.

POST /v1/receive-payments
{
  "customerRef": {
    "fullName": "Bayside Builders LLC"
  },
  "txnDate": "2026-11-09",
  "refNumber": "5521",
  "totalAmount": 828,
  "paymentMethodRef": {
    "fullName": "Check"
  },
  "isAutoApply": true
}
  • GET/v1/bills
  • GET/v1/bills/{id}
  • POST/v1/bills
  • POST/v1/bills/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, customerId / vendorId, refNumber, status (paid | unpaid | all, invoices and bills), ids.

Required on create: vendorRef. qbXML: Bill Query, Add, Mod.

POST /v1/bills
{
  "vendorRef": {
    "fullName": "City Utilities"
  },
  "txnDate": "2026-11-01",
  "dueDate": "2026-12-01",
  "refNumber": "UT-1105",
  "expenseLines": [
    {
      "accountRef": {
        "fullName": "Utilities"
      },
      "amount": 312.4,
      "memo": "October electric"
    }
  ]
}
  • GET/v1/bill-payments
  • GET/v1/bill-payments/{id}
  • POST/v1/bill-payments
  • POST/v1/bill-payments/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, customerId / vendorId, refNumber, status (paid | unpaid | all, invoices and bills), ids.

Required on create: payeeEntityRef, bankAccountRef, appliedTo. qbXML: BillPaymentCheck Query, Add, Mod.

POST /v1/bill-payments
{
  "payeeEntityRef": {
    "fullName": "City Utilities"
  },
  "txnDate": "2026-11-20",
  "bankAccountRef": {
    "fullName": "Checking"
  },
  "refNumber": "4188",
  "appliedTo": [
    {
      "txnId": "1F4-1731000000",
      "paymentAmount": 312.4
    }
  ]
}
  • GET/v1/accounts
  • GET/v1/accounts/{id}
  • POST/v1/accounts
  • POST/v1/accounts/{id} (update, needs editSequence)

Filters: limit (1–150), cursor, updatedAfter, updatedBefore, nameContains, nameStartsWith, status (active | inactive | all), ids.

Required on create: name, accountType. qbXML: Account Query, Add, Mod.

POST /v1/accounts
{
  "name": "Shop Equipment",
  "accountType": "FixedAsset",
  "accountNumber": "1550",
  "desc": "Tools and shop equipment"
}

Company

GET/v1/company

CompanyQuery and HostQuery in one call: company name, address, fiscal year, QuickBooks product and supported qbXML versions.

Raw qbXML

POST /v1/qbxml takes a full qbXML document (Content-Type: application/xml) and answers in qbXML, or as { qbxml, responses } JSON when you send Accept: application/json. It is validated first: malformed XML fails fast with the line and column (0x80040400) instead of failing on your customer’s PC. In production the document is passed through unchanged. The sandbox simulates Query/Add/Mod for the core objects, iterators and onError, and answers statusCode="3250" for messages it does not simulate. See the qbXML message reference.

Errors

Every error says what failed, why, and how to fix it, and carries the QuickBooks status code when there is one:

HTTP 409
{
  "error": {
    "type": "invalid_request_error",
    "code": "edit_sequence_out_of_date",
    "message": "The provided edit sequence \"1731000000\" is out-of-date (current is \"1731000123\").",
    "why": "The provided edit sequence is out-of-date.",
    "fix": "Someone changed this invoice after you read it. GET /v1/invoices/1F4-1731000000 again, re-apply your change and send the new editSequence.",
    "qbStatusCode": "3200",
    "field": "editSequence",
    "docs": "/errors/3200"
  }
}
HTTPWhen
400Invalid input; QuickBooks codes 3070, 3100, 3140, 3210; qbXML parse errors (0x80040400)
401Missing, unknown or revoked key
402Production call without a paid plan
404Unknown resource, or 3120 object not found
4093200 stale editSequence; connection not synced yet; no connection
429Demo key rate limit (30 calls a minute per IP)
202Production call queued longer than 25s: poll the job

Browse every Web Connector and SDK error code with causes and fixes.

Web Connector guide

  1. Dashboard → Connections → New connection. One connection per company file.
  2. Send your customer the hosted setup page (/connect/…). It walks them through opening the Web Connector, adding the .qwc file, granting access and entering the password, and shows “Connected” live.
  3. On the first sync LedgerWire records the company name, QuickBooks edition and version. You get a connection.synced webhook and an email.
  4. The .qwc schedules a run every minute. Each run, the Web Connector calls authenticate, then sendRequestXML / receiveResponseXML until the queue is empty.
  5. No check-in for 24 hours marks the connection stale, sends a connection.stale webhook and an email with the usual fixes.

Need a .qwc for your own SOAP server instead? Use the free .qwc generator.

Jobs and 202s

Production calls are queued as jobs. LedgerWire holds the HTTP request open for up to 25 seconds; if the Web Connector answers in time you get the normal response. Otherwise you get 202 with a job: poll GET /v1/jobs/{id} or wait for the job.completed / job.failed webhook. Jobs left in flight by a broken Web Connector session are re-queued automatically.

HTTP 202
{
  "object": "job",
  "id": "job_8f2kQ…",
  "status": "queued",
  "resource": "invoices",
  "method": "POST",
  "connectionId": "conn_…",
  "pollUrl": "/v1/jobs/job_8f2kQ…"
}

Webhooks

Register endpoints in Dashboard → Webhooks. Events: job.completed, job.failed, connection.synced, connection.stale. Each delivery is a JSON POST signed with LedgerWire-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 of t + "." + body with your endpoint secret. Answer any 2xx within 8 seconds.

API explorer

Runs real calls against the shared demo sandbox (simulated sample data). Log in to use your own sandbox and try creates and updates.

Using the shared demo key: read-only and rate-limited (30 calls a minute).

curl "https://ledgerwire.vibiz.app/v1/invoices?limit=3&status=unpaid" \
  -H "Authorization: Bearer lw_test_demo_public_sandbox"
response
Press “Run in sandbox” to send a real request.