API keys, permissions and data conventions

Authentication & company access

Send Authorization: Bearer nrm_… on every authenticated request. Norman shows the full key once; the key list shows its prefix, permissions and last use. To rotate a key, create a replacement, update your integration and then revoke the old key.

Authorization: Bearer nrm_your_api_key
Content-Type: application/json

One key, one company

A key always uses the company it was created for. GET /companies/ returns that company. Paths containing {company_pk} use its publicId. Company IDs supplied in URLs, request bodies or an optional X-Company-Id header must match the key. Referenced clients, documents and transaction items must also belong to that company.

Choose the permissions your integration needs

Read and write permissions are separate: write_invoices does not include read_invoices. The Invoicing preset includes client and invoice reads and writes. full_access covers the operations in this reference for the key’s company. Expired or revoked keys stop working; access also ends if the creator’s account is disabled or company access is removed.

Some workflows need several permissions. Document batch processing and metadata corrections require write_documents and write_transactions. Matching invoice payments requires invoice and transaction permissions. Product catalog operations use invoice permissions. Each reference entry lists the full requirement. Saving client details from an invoice requires write_clients.

Data conventions

Money, dates and identifiers

• Transaction amounts use minor currency units. For EUR, 4999 means €49.99. Invoice line rate: 15000 means €150.00 per unit. Transaction amounts can be returned as decimal strings, for example "-4999.00". Preserve precision when converting them.
• Transaction expenses use a negative amount and cashflowType: "EXPENSE". Invoice quantities and unit prices are positive. vatRate: 19 means 19%.
• JSON field names use camelCase: valueDate, invoicedItems, dueTo. Use the query names in the reference, such as page_size and date_from.
• Dates use YYYY-MM-DD; timestamps use ISO 8601 with a timezone. A transaction’s valueDate is a timestamp.
• Use the UUID returned by the resource: usually publicId, or pk for tax reports. Check its response schema. Enum values are case-sensitive. For example, write invoice status: "draft" and client clientType: "business". Some response fields contain display labels such as "Draft" or "Business"; use the request schema when sending values back.

Pagination & filtering

List responses contain count, next, previous and results. Use page and page_size, or follow next until it is null. The default page size can differ by resource; request an explicit size. The configured maximum is normally 1,000.

curl --fail-with-body "https://api.norman.finance/api/v1/accounting/transactions/?date_from=2026-09-01&date_to=2026-09-30&page=1&page_size=100" \
  -H "Authorization: Bearer $NORMAN_API_KEY"

Use PATCH to update selected fields. Deletion and verification can be refused when accounting or document state prevents the change.