Skip to content

Clients

A client starts as a prospect the moment you create it. It can receive invoices immediately; it can only receive money once onboarding is complete and underwriting has approved it.

Lifecycle

Status Meaning Can send invoices Can be financed
pending_approval Created, or in onboarding, or awaiting underwriting Yes No
active Approved, limit assigned Yes Yes
suspended Temporarily blocked Yes No
inactive Deactivated, relationship dormant Yes No
archived Closed No No

These five values are the complete set — status is never anything else. A newly created client is pending_approval and additionally carries isProspect: true until it has a financing relationship. There is no prospect status: prospect is the flag, not the state. Where the client sits inside onboarding is a separate field — read onboarding state, not the client status.

Invoices are accepted in every state except archived. Those flagged for financing before the client is active wait, and are picked up automatically the moment approval lands — no resubmission.

Status transitions arrive as client.status_changed webhooks.

Create a client

POST /clients Partner writes

Registers one of your users as a Noja prospect and returns a ready-to-use onboarding URL in the same response.

Request

Field Type Notes
countryCode string Required NL
registrationNumber string Required Company registration number — see formats
companyName string Required Replaced by the registry name once we enrich
contact object Required firstName, lastName, email, phone
consent object Optional Required before financial data is accepted. Omit it and Noja records consent when the client signs — see Consent
tradeName string Optional Handelsnaam, when it differs from the registered name
partnerReference string Optional Your own user or tenant ID, echoed back everywhere
language string Optional nl (default), en or fi
Request body
{
  "countryCode": "NL",
  "registrationNumber": "68123456",
  "companyName": "Van Dijk Installatietechniek",
  "contact": {
    "firstName": "Sanne",
    "lastName": "van Dijk",
    "email": "sanne@vandijk-installatie.nl",
    "phone": "+31612345678"
  },
  "consent": {
    "obtainedAt": "2026-09-14T09:31:04Z",
    "method": "in_product_checkbox",
    "evidenceRef": "ptr-consent-4471a9"
  },
  "partnerReference": "ptr-user-88213"
}

Response · 201

{
  "clientId": "0193f2a1-8c4e-7b21-9d3f-1a2b3c4d5e6f",
  "countryCode": "NL",
  "registrationNumber": "68123456",
  "companyName": "Van Dijk Installatietechniek B.V.",
  "status": "pending_approval",
  "isProspect": true,
  "partnerReference": "ptr-user-88213",
  "onboarding": {
    "mode": "hosted",
    "url": "https://aanvraag.noja.nl/?partnerAccess=p_7f2a91&ref=0193f2a1",
    "expiresAt": "2026-10-14T09:31:04Z"
  },
  "createdAt": "2026-09-14T09:31:04Z"
}

The onboarding.url is the Mode B hand-off. Ignore it if you are collecting the data yourself.

Errors

Status Code When
409 client_exists That registration number is already registered. The body carries the existing clientId — treat it as success and continue.
422 validation_failed Registration number does not match its country's format, or the contact is incomplete.

Read a client

GET /clients/{countryCode}/{registrationNumber} Noja writes

Current state of one client: status, onboarding progress, and a headline capacity figure once approved.

{
  "clientId": "0193f2a1-8c4e-7b21-9d3f-1a2b3c4d5e6f",
  "registrationNumber": "68123456",
  "companyName": "Van Dijk Installatietechniek B.V.",
  "status": "active",
  "isProspect": false,
  "partnerReference": "ptr-user-88213",
  "onboarding": {
    "state": "signed",
    "completedAt": "2026-09-18T14:02:55Z",
    "signing": { "state": "signed", "provider": "scrive" }
  },
  "capacity": {
    "availableCredit": { "amount": 1840000, "currency": "EUR" },
    "creditUsedPercentage": 26.4
  }
}

capacity is null until the client is active. It is a summary for showing headroom in a list view; for the full commercial picture use credit conditions.

Book coverage

GET /clients/{countryCode}/{registrationNumber}/book-coverage Noja writes

How much of the client's book Noja holds, and whether it reaches back far enough to price them. Poll this after a backfill instead of guessing.

Three months is the minimum that produces a limit. Twelve months gives materially better pricing, because payment-behaviour variance is what narrows the rate. Below three months sufficientForPricing stays false and no terms are issued.

This endpoint measures depth, not completeness. It can tell you the oldest invoice Noja holds; it cannot tell you whether the invoices you chose to send are all of them. Nothing can — see Every invoice goes to Noja.

{
  "monthsCovered": 11,
  "invoiceCount": 284,
  "earliestIssueDate": "2025-10-02",
  "latestIssueDate": "2026-09-11",
  "distinctDebtors": 37,
  "sufficientForPricing": true,
  "qualityTier": "good",
  "recommendation": "Send one more month to reach the 12-month tier."
}
qualityTier Meaning
insufficient Under three months. No limit can be issued.
minimal Three to six months. Limit issued, conservative pricing.
good Six to twelve months.
complete Twelve months or more. Best available pricing.

complete describes the time span covered, not the completeness of the book within it.

Limit and fees

GET /clients/{countryCode}/{registrationNumber}/credit-conditions Noja writes

The full commercial terms — limit, utilisation, pricing, and effective APR.

Terms appear as soon as there is enough history to price them, which is usually before the client is approved. state tells you how much weight to give them:

state Meaning Safe to show as a firm offer
indicative Priced from history, not yet underwritten No — label it an estimate
pending_approval Submitted, in underwriting No
approved Underwritten and live Yes
declined Underwriting declined the client No

Before there is enough history to price anything, the endpoint returns 409 terms_not_available with a reason of insufficient_history.

Response

Facility terms

These govern every invoice the client sends. They are agreed once, not per invoice.

Field Type Meaning
advanceRate number The share of an invoice's face value Noja advances, 0–100. Agreed at onboarding, and applied to every invoice that does not request its own rate.
requestedAdvanceRate number What the client asked for at onboarding, before underwriting. Kept for comparison; advanceRate is what applies.
financingMode enum whole_book (standard) or selective. Determines what happens to an invoice sent without a financingIntent.

Status and exposure

Field Type Meaning
state enum indicative, pending_approval, approved, declined
updatedAt timestamp When these terms last changed
totalCreditLimit money Assigned limit
temporaryCreditLimit money Uplift, when one is active
temporaryCreditLimitFrom date Start of the uplift window
temporaryCreditLimitTo date End of the uplift window
usedCredit money Drawn and not yet repaid
outstandingCredit money Financed invoices awaiting debtor settlement
effectiveCreditLimit money Total including any temporary uplift
availableCredit money Effective limit minus used
creditUsedPercentage number Utilisation, 0–100
### Cost

Separate from the advance rate, and easily confused with it: advanceRate is how much the client receives, the fields below are what it costs them.

Field Type Meaning
pricing string Pricing band label
additionalFinancingPrice string Surcharge beyond the base term
effectiveAprBase number Effective APR at the base rate
effectiveAprAdditional number Effective APR including surcharge
openingFee money One-off fee charged at activation
averagePaymentTermCurrent integer Debtors' current average days-to-pay
averagePaymentTermHistory integer The same figure across full history
conditionsDetails array Label/value pairs for display
{
  "state": "approved",
  "updatedAt": "2026-09-19T08:40:12Z",
  "advanceRate": 80,
  "requestedAdvanceRate": 85,
  "financingMode": "whole_book",
  "totalCreditLimit": { "amount": 2500000, "currency": "EUR" },
  "temporaryCreditLimit": null,
  "usedCredit": { "amount": 660000, "currency": "EUR" },
  "outstandingCredit": { "amount": 660000, "currency": "EUR" },
  "effectiveCreditLimit": { "amount": 2500000, "currency": "EUR" },
  "availableCredit": { "amount": 1840000, "currency": "EUR" },
  "creditUsedPercentage": 26.4,
  "pricing": "Band B",
  "additionalFinancingPrice": "0.8% / 15 days",
  "effectiveAprBase": 28.1,
  "effectiveAprAdditional": 34.6,
  "openingFee": { "amount": 50000, "currency": "EUR" },
  "averagePaymentTermCurrent": 41,
  "averagePaymentTermHistory": 38,
  "conditionsDetails": [
    { "label": "Invoice minimum", "value": "€250" },
    { "label": "Maximum term", "value": "90 days" }
  ]
}

Surfacing this to the user

availableCredit and advanceRate are the two figures a user acts on: how much capacity is left, and what share of an invoice turns into cash. The APR fields exist because Dutch consumer-facing credit disclosure expects them — show them where a user is deciding, not in a settings page.

Do not present advanceRate as something adjustable per invoice. It is a term of the client's agreement; changing it is a conversation with Noja, not a toggle.

Changes to any of these arrive as client.credit_conditions_updated.