| name | api-usage |
| description | Reference for calling existing HMIS REST APIs. Use when consuming/invoking an HMIS endpoint — verifying data via API during issue investigation, writing a debug curl/script call, or checking an endpoint's request/response shape before writing a caller. Covers auth header conventions, the standard response envelope, and the developer_docs/api/using-apis/ module index. For building or extending an endpoint, use api-development instead.
|
| user-invocable | true |
HMIS API Usage Guide
When This Applies
Any time you need to call an HMIS REST endpoint that already exists — not create one:
- Verifying a bill/payment/balance via the read-only APIs while investigating an issue
- Writing a one-off curl/script call to check data during debugging
- Confirming an endpoint's request/response shape before writing a caller against it
- Wiring an API call into the in-app AI Chat tool-calling flow (
AnthropicApiService)
If you're instead building or extending an endpoint (new @Path class or new method on one),
use the api-development skill — this one has no implementation detail.
Auth Headers
Every request needs an auth header. Which one depends on the module — check the table below
before guessing:
| Header | Used by |
|---|
Finance | Default for most modules (bills, balances, pharmacy, inward, users, etc.) |
Token | Channel/booking appointments, consultant management |
Config | Reading/updating ConfigOption application settings |
FHIR | FHIR Patient resource endpoints |
| Custom (URL/JSON/Basic) | LIMS lab middleware |
| none | Membership scheme registration/payment (public) |
Send the key as the exact header name above, e.g. Finance: <apiKey>. A 401 Not a valid key
response means the key is invalid, retired, or expired (ApiKey.dateOfExpiary).
Response Envelope
Standard endpoints wrap responses the same way regardless of module:
{"status":"success","code":200,"data":{...}}
{"status":"error","code":400,"message":"..."}
POST duplicate-detection endpoints return a bare (non-wrapped) shape instead:
{"status":"already_exists","id":123,"name":"..."}
Always check status first, not just HTTP status code — some error conditions still return
HTTP 200 with "status":"error" in the body.
Module Index
developer_docs/api/using-apis/ has one self-contained reference file per module: base path,
auth header, request/response shapes, error codes. Load only the file for the module you
need — don't read the whole directory. Start from
developer_docs/api/using-apis/README.md
for the full, current table (module, file, auth header); it's kept up to date as new API docs
are added, so treat it as the source of truth rather than duplicating the list here.
If you're unsure which module owns the data you need, check README.md's table first — several
files disambiguate related-sounding endpoints (e.g. API_ADMISSION_DETAILS.md is a consolidated
index of which admission-related API to call).
Verifying Payments and Balances
A common task during issue investigation: confirm a bill's payments produced the correct balance
updates. Don't hand-roll this — follow
API_TESTING_WORKFLOWS.md:
fetch the bill (/api/costing_data/...), pull the matching balance-history endpoint per payment
method (drawer/deposit/staff-welfare/agent), and assert after == before + transactionValue
(with float tolerance, since credit-company payments have no history endpoint and refunds/
cancellations use negative or reversing entries). This same file also covers batch verification
and common troubleshooting symptoms (case-sensitive bill numbers, empty payments[] on
transfer/issue bills, etc.).
General Troubleshooting
| Symptom | Cause / Fix |
|---|
401 Not a valid key | Auth key invalid, retired user, or expired — check ApiKey.dateOfExpiary |
404 / entity not found | IDs and bill numbers are often case-sensitive; confirm exact format |
200 with "status":"error" | Check message, not just HTTP status — see Response Envelope above |
| Numeric fields don't match exactly | Use tolerance (abs(a - b) < 0.01) for currency comparisons, not == |
