Skip to content

Core concepts

Five conventions hold across every endpoint. Reading these first will save you the four integration bugs everyone hits.

Clients are addressed by registration number, never by our ID

Every client path is /clients/{countryCode}/{registrationNumber} — an ISO 3166-1 alpha-2 country code plus the company's national registration number.

You never have to store a Noja identifier. We return one (clientId) for logging and support, but no request requires it.

/clients/NL/68123456
/clients/NL/68123456/credit-conditions
/clients/NL/68123456/onboarding/steps/company

Invoices are addressed either by the invoiceId we return, or by your own invoiceNumber scoped to the client. Both work.

Registration number formats

The registration number is whatever the company's national business register issues. Two worked examples:

Country Identifier Format Example
NL KvK-nummer 8 digits, no dots or spaces 68123456
FI Y-tunnus 7 digits, hyphen, check digit 2597279-7

Countries we have not yet profiled accept letters, digits and hyphens up to 50 characters. A registration number that does not match a known format is rejected with validation_failed before anything is created.

Signing providers differ by country too, which is why onboarding submit returns a signing instruction rather than expecting you to know the provider. Read signing.method and follow it.

Every invoice goes to Noja

Noja's product is whole turnover. The client routes their entire invoice book through Noja — receivables and payables, financed or not — and Noja advances money against it. The book is the collateral; individual invoices are not assessed in isolation.

That makes completeness a correctness requirement, not a data-quality nicety:

Figure Computed across Wrong if the book is partial
Credit limit The whole receivables book Limit is set against collateral that is larger than Noja can see
Debtor spread Every debtor the client invoices Concentration risk is understated
Payment behaviour Every invoice and its settlement Average terms are skewed by whichever invoices were chosen
Shortfall recovery Proceeds of non-financed invoices Recovery is calculated against money Noja does not know exists

None of these degrade gracefully. They return a number that looks plausible and is wrong, which is worse than returning nothing.

What the client may and may not choose

Less than an integration built for selective invoice finance would assume.

Who decides
Whether an invoice reaches Noja Nobody — all of them must
The default advance rate Client and Noja, once, at onboarding
Which invoices are financed Noja, invoice by invoice
What share of one invoice is advanced Client may request; Noja sets what applies
Whether one invoice is withheld Client, by exception

A client on the standard facility has no per-invoice decision to make, and that is deliberate. Letting a client choose which receivables to finance is adverse selection: they keep the fast-paying debtors and pass on the slow ones, while the pricing was set on the average of the whole book. The facility only works because the selection is Noja's.

Withholding a single invoice stays possible for the genuine cases — a disputed amount, a debtor the client would rather chase themselves. It keeps the invoice in the book as collateral and it is still collected through Noja's collection partner. It is an exception, not a workflow.

There is no API affordance that proves your book is complete, and Noja does not attempt to detect gaps. Completeness is a term of the partner agreement, enforced operationally. Sending a subset is not a degraded integration; it is a broken one.

Noja will not accept invoices or company financials for a client without a record that the client agreed to share them. That record can arrive two ways:

  • You capture it and send the consent object when you create the client.
  • The client signs through Noja's own onboarding flow, in which case Noja records consent automatically — the agreement covers it.

Send the consent object when you have it. If you do not, create the client anyway and hand the user to the hosted onboarding flow; consent is recorded the moment they sign.

Until one of those happens, POST /invoices returns 403 consent_required. Client creation and onboarding are never blocked — only financial data is.

Money is always in minor units

Every amount is an integer of cents plus a currency, never a decimal.

{ "amount": 424250, "currency": "EUR" }   // €4,242.50

This is deliberate: it removes float rounding from financing maths entirely. Sending 4242.50 is rejected with validation_failed.

The most common integration bug

Sending euros where cents are expected under-reports an invoice by a factor of 100, and the invoice will usually still be accepted — it just scores as trivially small. Multiply by 100 at the boundary and assert it once in your tests.

Every write takes an idempotency key

Send Idempotency-Key on every POST and PATCH. Replaying a key returns the original response unchanged rather than creating a duplicate — safe for retries, queue redelivery, and nervous cron jobs.

-H "Idempotency-Key: inv-68123456-2026-0417"

Keys live 24 hours. Use something derived from your own data rather than a random UUID, so a retry after a crash reuses the same key.

Dates are ISO 8601

Calendar dates are YYYY-MM-DD. Timestamps are RFC 3339 in UTC with a Z suffix.

Invoice dates are calendar dates — an invoice is issued on a day, not at an instant. Event timestamps are full timestamps.

{
  "issueDate": "2026-08-30",
  "occurredAt": "2026-09-14T10:02:47Z"
}

One error shape

Every failure returns the same envelope. fields is present only on validation errors.

{
  "error": {
    "code": "validation_failed",
    "message": "Check the highlighted fields",
    "fields": {
      "registrationNumber": "invalid",
      "amount.currency": "unsupported"
    }
  }
}

Branch on code, never on message — messages are written for humans and will change. The full code list is in Errors and limits.

Who writes what

This is the conceptual spine of the API, and it is worth internalising before you build.

Data Owner Partner can change it
Invoice amount, dates, counterparty Partner Yes, until the invoice is financed
Invoice payment outcome (history) Partner Yes, optionally
financingIntent override Partner Yes, by exception, while the due date is ahead
Partner's own invoice status Partner Yes, free-text, never interpreted by Noja
Consent record Either You send it, or Noja records it at signing
Default advance rate Both Client requests at onboarding, Noja agrees; read-only after
Per-invoice advance rate Both Partner may request one; Noja sets what applies
Which invoices are financed Noja No partner input
Completeness of the book Partner Contractual, not enforced by the API
Company name, contact, KYC data Partner Yes, through onboarding
Invoice state Noja No
Financing decision, approved amount, fee Noja No
Credit limit, pricing, APR Noja No
Client status Noja No

Attempting to write a Noja-owned field returns 422 validation_failed naming that field, rather than silently ignoring it.

Every endpoint page marks each operation as Partner writes or Noja writes so this stays visible as you read.