Home Integration API reference
REST API for integrations and external apps
Dashboard
GET https://billdiary.com/api/v1/integration/global-search
Query — q (required, 2–120 characters). Optional format json (default) or csv — streamed UTF-8 CSV with BOM, same up-to-40 hits as JSON (group, label, meta, type, id); no separate pagination. Otherwise returns JSON. Uses the same permission gates and location scoping as the web header search (e.g. sell list permissions, purchase.view, customer/supplier view, product view).
Each result includes group, label, meta, type (sell|purchase|contact|product), and id for follow-up calls to the matching integration endpoints.
Response 200 — JSON: data.results, data.q. CSV: file download global-search-{business_id}-{timestamp}.csv. 422 if q is missing or too short.
Headers
Authorization: Bearer YOUR_ACCESS_TOKEN Accept: application/json
GET https://billdiary.com/api/v1/integration/dashboard/totals
Requires dashboard.data. Same aggregate pipeline as the home screen totals (HomeController@getTotals): purchase and sell amounts (inc tax), dues, purchase/sell returns, expense total, and net (sell minus invoice due minus expense), with ledger discount adjustments applied like the web.
Query — start and end (required, inclusive dates, Y-m-d); optional location_id (must belong to the business and be in your permitted locations); optional user_id (filters by transactions.created_by, same role as the web dashboard user filter). Optional format json (default) or csv — streamed UTF-8 CSV with BOM, one data row: data_json and meta_json (JSON in each cell, matching the JSON data and meta objects after a normal encode/decode round-trip).
Response 200 — JSON: data with the total fields (e.g. total_purchase, purchase_due, total_sell, invoice_due, total_expense, return and payment totals, net), and meta echoing start, end, location_id, user_id. CSV: file download dashboard-totals-{business_id}-{timestamp}.csv. 403 without permission or when location_id is not allowed. 422 for validation or unknown location.
{
"data": {
"total_purchase": 1000.0,
"purchase_due": 100.0,
"total_sell": 2000.0,
"invoice_due": 200.0,
"total_expense": 50.0,
"total_purchase_return": 0.0,
"total_sell_return": 0.0,
"net": 1750.0
},
"meta": {
"start": "2024-01-01",
"end": "2024-01-31",
"location_id": null,
"user_id": null
}
}
GET https://billdiary.com/api/v1/integration/dashboard/stock-alerts
Requires stock_report.view. Same data source as the home Product stock alert table (ProductUtil::getProductAlert): variations where qty_available <= alert_quantity, ordered by stock ascending.
Query — optional location_id (permitted location); per_page (1–100, default 20); page; optional q (minimum 2 characters when sent) — product name, sku, variation or template name, sub_sku, location name, or numeric product or variation id (LIKE wildcards in q are escaped). Optional format=csv — UTF-8 CSV (BOM) of all matching rows (same filters; page / per_page ignored). Download name dashboard-stock-alerts-{business_id}-{Ymd_His}.csv.
Response 200 — data array of rows with variation_location_detail_id, location_id, product/variation labels, stock, alert_quantity, unit, and meta pagination plus location_id and echoed q when used; or a CSV download when format=csv.
GET https://billdiary.com/api/v1/integration/dashboard/purchase-payment-dues
Requires purchase.view. Unpaid purchases whose pay-term due date falls within the next 7 days (same DATEDIFF logic as HomeController@getPurchasePaymentDues).
Query — optional location_id; per_page (1–100, default 20); page; optional q (minimum 2 characters when sent) — ref_no, supplier name, business name, mobile, POS contact_id, or numeric transaction id. Optional format=csv — UTF-8 CSV (BOM) of all matching rows (same filters; page / per_page ignored). Download name dashboard-purchase-payment-dues-{business_id}-{Ymd_His}.csv.
Response 200 — data rows with transaction_id, supplier (display name), ref_no, final_total, total_paid, amount_due, and meta pagination plus echoed q when used; or a CSV download when format=csv.
GET https://billdiary.com/api/v1/integration/dashboard/sales-payment-dues
Requires sell.view or direct_sell.view. Unpaid final sales with pay terms, due within 7 days (same logic as HomeController@getSalesPaymentDues).
Query — optional location_id; per_page (1–100, default 20); page; optional q (minimum 2 characters when sent) — invoice_no, ref_no, customer name, business name, mobile, POS contact_id, or numeric transaction id. Optional format=csv — UTF-8 CSV (BOM) of all matching rows (same filters; page / per_page ignored). Download name dashboard-sales-payment-dues-{business_id}-{Ymd_His}.csv.
Response 200 — data rows with transaction_id, customer, invoice_no, final_total, total_paid, amount_due, and meta pagination plus echoed q when used; or a CSV download when format=csv.
GET https://billdiary.com/api/v1/integration/dashboard/calendar-events
Requires dashboard.data. Same merge as HomeController@getCalendar (AJAX): restaurant bookings when listed in events, plus module calendarEvents (e.g. Essentials todos/holidays when modules expose them).
Query — start and end (required, visible range); optional events[] (e.g. events[]=bookings); optional location_id; optional user_id (only for business Admin or superadmin, must be a user in the business). Optional format json (default) or csv — streamed UTF-8 CSV with BOM, one row per merged event: index (0-based order) and event_json (JSON in the cell, same object as the corresponding JSON data[] entry). Download name dashboard-calendar-events-{business_id}-{Ymd_His}.csv.
Response 200 — JSON: data is an array of FullCalendar-style objects; meta echoes range and filters. Or a CSV download when format=csv (no JSON meta in the file; use the same query parameters as for JSON).
Requires dashboard.data. Same JSON as DashboardAnalyticsController (dashboard v2 / home insight API). Optional query on all paths: start, end (default last ~30 days through today if omitted), location_id (must be permitted). Optional format=csv on any of the paths below — streamed UTF-8 CSV with BOM, one data row plus header: column data_json contains JSON matching the entire JSON response body for that path (same as when the root object is returned as JSON). Filename pattern {endpoint}-{business_id}-{Ymd_His}.csv (e.g. dashboard-analytics-kpis-1-20260112_120000.csv).
| GET path | Web equivalent |
|---|---|
/api/v1/integration/dashboard/analytics/kpis | /home/api/kpis |
.../widgets | /home/api/widgets |
.../insights | /home/api/insights |
.../trends | /home/api/trends |
.../distributions | /home/api/distributions |
.../alerts | /home/api/alerts |
.../activity | /home/api/activity |
.../phase1 … phase7 | /home/api/phase1 … phase7 |
The .../activity path also accepts optional q (minimum 2 characters when sent) — matches invoice_no, ref_no, contact name or supplier business name, transaction creator first or last name, or numeric transaction id. The response echoes q when used (alongside items).
GET https://billdiary.com/api/v1/integration/custom-dashboards/available-widgets
Requires dashboard.data. Returns the same merged widget definitions the web Custom Dashboard builder loads from installed modules: ModuleUtil::getModuleData('CustomDashboardOptions') (each module’s DataController::CustomDashboardOptions, e.g. Essentials attendance, holiday, reminders, leaves). Keys in data are module names; values are arrays of descriptors (name, label, size, range, location, show_data, etc.).
Optional query format json (default) or csv — streamed UTF-8 CSV with BOM, one row per widget: module (same key as in JSON data), index (0-based position in that module’s descriptor array), widget_json (JSON in the cell, same object as data[module][index] in JSON). Modules with no widgets produce no rows. Download name custom-dashboard-available-widgets-{business_id}-{Ymd_His}.csv.
Modules must be installed (version row in system) to appear. If none expose options, data is an empty object. Saving or loading user-specific dashboard layouts still depends on the optional CustomDashboard add-on module when deployed.
Response 200 — JSON: data (object keyed by module), meta.modules (module name list); or a CSV download when format=csv.