Finance QB REST API

QuickBooks REST API

Introduction

The HMIS QuickBooks REST API exposes financial data through HTTP endpoints that external accounting systems can call programmatically. QuickBooks Online, custom ERP integrations, and automated accounting pipelines use this API to pull revenue, payment, and stock data directly — without manual file export and import.

Base URL and Authentication

• Base path: /api/qb
• Authentication: Pass your API key in the Finance HTTP header.

GET /api/qb/dailyReturn?date=2026-05-15
Finance: your-api-key-here

API keys are issued and managed through the HMIS API Key Management console. Keys must be active, not expired, and not retired.

Available Endpoints

Method	Endpoint	Description
GET	/api/qb/dailyReturn	Daily OPD billing and payment summary
GET	/api/qb/inwardJournal	Inpatient billing journal entries
GET	/api/qb/pharmacyGrn	Pharmacy goods received (stock purchases)
GET	/api/qb/itemList	Full item/service list with QB account mappings
GET	/api/qb/doctors	Doctor/consultant list with payment details
GET	/api/qb/professionalFees	Doctor professional fee payments
GET	/api/qb/creditCompany	Credit company receivables
GET	/api/qb/cashierSummary	Cashier collection summary
GET	/api/qb/paymentMethods	Collections by payment method
GET	/api/qb/stockValuation	Current pharmacy stock valuation

Common Query Parameters

Parameter	Description	Example
date	Single date (for daily data)	2026-05-15
from	Start date for range queries	2026-05-01
to	End date for range queries	2026-05-31
department	Filter by department code	OPD, PHARMACY
format	Response format	json (default), iif

Date format: yyyy-MM-dd

Response Format

All endpoints return JSON:

{
  "status": "success",
  "code": 200,
  "data": {
    "date": "2026-05-15",
    "entries": [
      {
        "account": "OPD Revenue",
        "amount": 125000.00,
        "paymentMethod": "Cash",
        "docNum": "B-12345",
        "qbClass": "OPD"
      }
    ],
    "total": 125000.00
  }
}

Error responses:

{
  "status": "error",
  "code": 401,
  "message": "Invalid or expired API key"
}

IIF Format via API

To retrieve IIF-formatted output (for systems that prefer the file format):

GET /api/qb/dailyReturn?date=2026-05-15&format=iif
Finance: your-api-key-here

The response body is the IIF file content (tab-delimited), suitable for direct import into QuickBooks Desktop.

Integration Setup

To configure an external system to use the HMIS QB API:

1. Obtain an API key from the HMIS administrator.
2. Configure the external system with the HMIS base URL and API key.
3. Set up a scheduled job (daily, nightly, or real-time) to call the relevant endpoints.
4. Map the returned accounts and classes to the external system's chart of accounts.

Rate Limiting and Best Practices

• Call daily endpoints once per day after the business day closes (recommended: midnight or early morning).
• Do not call real-time endpoints more than once per minute.
• Cache the item list endpoint — it changes infrequently and does not need to be polled daily.

Technical Reference

Item	Detail
REST class	@Path("qb") in the REST API layer
Authentication	Finance header → ApiKeyController.findApiKey() — checks expiry, retired, activated
Date format	yyyy-MM-dd HH:mm:ss in Gson serialisation
Registration	Must be listed in ApplicationConfig.addRestResourceClasses()
Related	QB Integration Overview, REST API Development Guide