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

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:
| Event | When |
|---|---|
| invoice.issued, credit_note.issued, debit_note.issued | A sales document is issued |
| bill.recorded, supplier_note.recorded, import.recorded | A purchase is recorded |
| document.cancelled | An invoice, bill or note is cancelled |
| payment.received, payment.made | Money comes in or goes out |
| journal.posted | Any voucher is posted |
| approval.requested, approval.approved | Maker-checker |
| vat_return.filed, payroll.posted | Month-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.