API Integration Guide

Authentication

Exchange your Metiz key for a JWT access token. The token is valid for one hour.

POST /api/v1.0/auth/token
Content-Type: application/json

{ "metiz_key": "<your-metiz-key>" }

→ 200 OK
{ "result": "success", "token": "<JWT>", "system": "exact" }

• token — the JWT to send on every other call.
• system — the accounting backend for this tenant: exact, yuki or demo.

Before the token expires, renew it with POST /api/v1.0/auth/refresh (send the current token as a bearer header). On a 401, authenticate again.

Request headers

The Administration header is only a filter within your own tenant's data — it never changes which tenant you access. Valid IDs come from GET /administrations.

Responses

Data endpoints return a consistent envelope:

{ "result": "success", "message": "", "data": [ ... ] }

Fetching data

Send the token as a bearer header on every data request. Example — GL transactions for one administration over a date range:

GET /api/v1.0/gl_transactions?From=2026-01-01&To=2026-03-31
Authorization: Bearer <JWT>
Administration: <admin-id>

Common endpoints — all GET, all returning the standard envelope:

• /administrations — companies / divisions in your tenant.
• /gl_accounts — chart of accounts.
• /gl_transactions — GL transactions, with date and period filters.
• /financial_periods — available financial periods.
• /payables & /receivables — outstanding creditor / debtor items.
• /journals, /relations — journals and contacts.

See the API Endpoints page for the full list and parameters.

Pagination

Every data endpoint accepts page (1-indexed, default 1) and page_size (default 1000, maximum 100 000) as query parameters. Larger values are silently capped. Responses carry data, total, page and page_size so a client can drive a simple while (page * page_size < total) loop.

GET /api/v1.0/gl_transactions?page=2&page_size=5000
Authorization: Bearer <JWT>

Incremental sync

Every record carries a Metiz Updated At field — an ISO 8601 UTC timestamp set whenever Metiz persists the row (full reload, nightly delta, or a soft-delete bump). Clients keep the highest timestamp they've seen and pass it on the next call to receive only what changed.

GET /api/v1.0/gl_transactions?updated_since=2026-05-26T00:00:00Z
Authorization: Bearer <JWT>

The response includes a top-level latest_updated_at field — the highest stamp across the matching rows. Store it and pass it as updated_since on the next call:

{
  "result": "success",
  "data": [ /* rows changed since 2026-05-26T00:00:00Z */ ],
  "total": 1248,
  "page": 1,
  "page_size": 1000,
  "latest_updated_at": "2026-05-27T08:32:33Z"
}

Soft deletes also bump Metiz Updated At — combine ?updated_since= with ?include_deleted=true to discover both updates and deletions in the same call. The deleted_date field is non-null on deleted rows.

Bulk export (Parquet)

For data pipelines and Power BI, add ?format=parquet to any data endpoint to receive an Apache Parquet binary (Content-Type: application/vnd.apache.parquet) instead of JSON. One request returns the full filtered set — the page/page_size parameters do not apply — so it's the fastest way to pull an entire endpoint.

GET /api/v1.0/gl_transactions?format=parquet
Authorization: Bearer <JWT>
→ 200  Content-Type: application/vnd.apache.parquet  (binary)

The updated_since and include_deleted filters still apply, so an incremental pull can be streamed as Parquet too: ?format=parquet&updated_since=<ISO>.

?format=parquet works on every endpoint that returns rows — the ledger endpoints above, plus /administrations, /operands, and the flattened forms of /statement_lines, /gl_account_mappings and /budgets. For the configuration endpoints, pass ?flattened=true alongside it (their default nested shape can't be tabularized).

Recommended flow

1. Call POST /auth/token with your metiz_key — store the token.
2. Optionally check GET /status — confirm data is ready before relying on a full dataset.
3. Call the data endpoints you need with the Authorization header and any filters.
4. If a call returns 202, retry after a short delay — data is still syncing.
5. Refresh the token before the one-hour expiry, or re-authenticate on the first 401.

A token only ever exposes the data of the metiz_key it was issued for — there is no cross-tenant access. For a Metiz key or access issues, contact your Metiz representative.