MMHS Finance
Developers

API and webhooks

Connect your other systems: API keys, rate limits, errors and signed webhooks.

Developers: API keys with their access and expiry, and webhook endpoints with their recent deliveries.
Developers: API keys with their access and expiry, and webhook endpoints with their recent deliveries.

The API gives other systems the same operations as the screens: read the ledger and reports, issue invoices, record bills and payments. It is part of the Corporate plan. The full list of endpoints is in the API reference.

Keys

An owner or admin creates keys under Developers (in the Account menu). A key is shown once; we keep only its fingerprint. Each key has its own access (read only, or read and post as an accountant) and can be limited to one company or expire.

# MHS_API is the API address shown at the top of the API reference
curl "$MHS_API/v1/companies" \
  -H "Authorization: Bearer mhs_live_…"

Conventions

  • Amounts are strings with up to four decimals; dates are YYYY-MM-DD.
  • Every company-specific path starts with /v1/companies/{companyId}.
  • A write can be held for approval (HTTP 202 with an approval) when the company's approval rules apply.
  • Errors are { "error": { "code": "…", "message": "…" } } with HTTP 4xx. Common codes: INVALID_API_KEY (401), FORBIDDEN (403), NOT_FOUND (404), INVALID_INPUT (400), JOURNAL_INVALID and other business rules (422), RATE_LIMITED (429), SUBSCRIPTION_REQUIRED or PLAN_FEATURE (402).
  • Limit: 120 requests a minute per key.

Webhooks

Add an endpoint under Developers (in the Account menu) and choose events:

EventWhen
invoice.issued, credit_note.issued, debit_note.issuedA sales document is issued
bill.recorded, supplier_note.recorded, import.recordedA purchase is recorded
document.cancelledAn invoice, bill or note is cancelled
payment.received, payment.madeMoney comes in or goes out
journal.postedAny voucher is posted
approval.requested, approval.approvedMaker-checker
vat_return.filed, payroll.postedMonth-end work

Each delivery is a POST with a JSON body { id, event, createdAt, companyId, data } and these headers: X-MHS-Event, X-MHS-Delivery and X-MHS-Signature: t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + body with your signing secret. Check the signature and reject old timestamps. Answer with any 2xx within 10 seconds; other answers are retried after 1, 4, 16, 64 and 256 minutes before the delivery is marked failed. Fetch the full record from the API using data.id.