Mosaic Hub API
A focused REST API for moving real financial data in and out of Mosaic Hub.
What is the Mosaic Hub API?
The Mosaic Hub API is the public, programmable surface of hub.mosaic.co.za. It is designed for partner systems, internal automation and bespoke integrations that need first-class access to the same data the Mosaic Hub portal works with - personal finance, accounting (Numbers), payroll and people management.
The v1 surface ships with one endpoint covering the most-requested integration scenario: ingesting supplier bills into the Numbers module for expense management. The roadmap expands the surface across Numbers, Personal and People with the same conventions described here.
Design principles
| Principle | What it means in practice |
|---|---|
| Version-first URLs | All paths start with /v1/. Breaking changes ship as /v2/, /v3/, etc. |
| Additive body evolution | Every request body carries schema_version (semver). Additive changes increment the minor/patch within the same URL version. |
| OpenAPI 3.2.0 | The machine-readable specification is the source of truth. |
| Problem details (RFC 7807) | Every non-2xx response is application/problem+json with a stable type URI. |
| HMAC-SHA256 signing | No bearer tokens. Every request is signed with a per-key secret. See Authentication. |
| Idempotent writes | Write endpoints require an Idempotency-Key header. Replays return the original response. |
| Asynchronous events | Server-side processing emits Mosaic Hub events so downstream automation can react in real time. |
Base URL
Base
https://api.mosaic.co.za
Quick start
- Contact Mosaic to provision an API credential. You receive an
api_key_identifier(UUID) and asigning_key(base64). - Read Authentication to learn how to sign requests.
- Pick an endpoint, e.g. Numbers / Spending Methods, and send your first request.
- Verify the resulting draft transaction inside the Mosaic Hub portal (Numbers → Spending Methods).
Endpoint catalogue
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /v1/healthz | Liveness probe (no auth). | - |
| POST | /v1/numbers-spending-methods | Ingest a supplier bill as a draft transaction. | numbers.spending-methods.write |
| POST | /v1/numbers-receivables-invoices | Batch-ingest receivables invoices; commit/void lifecycle. | numbers.receivables-invoices.write |
| POST | /v1/numbers-receivables-credit-notes | Batch-ingest receivables credit notes; commit/void lifecycle. | numbers.receivables-credit-notes.write |
| POST | /v1/numbers-receivables-quotes | Batch-ingest quotes; commit/accept/void/convert lifecycle. | numbers.receivables-quotes.write |
The full specification - including request and response schemas, every possible error code and end-to-end examples - lives in mosaic-hub-open-api.json. Import it into Postman, Insomnia or any OpenAPI tool to generate clients.