Voor ontwikkelaars

API-reference

Alle endpoints van de nl.legal incasso API, met de velden, regels en foutcodes die erbij horen. Deze pagina wordt gegenereerd uit de OpenAPI 3.1-specificatie, dus wat u hier leest is wat de API doet. Twee endpoints werken zonder API-key.

Naar de handleiding Interactieve versie

Basis

Basis-URL	`https://nl.legal/api/v1`
Authenticatie	`Authorization: Bearer nll_live_…`. Test-keys beginnen met `nll_test_` en maken nooit een echt dossier aan.
Bedragen	Altijd gehele getallen in eurocenten. € 1.250,00 is `125000`.
Specificatie	openapi.json (OpenAPI 3.1.0, versie 1.1.0)

Twee endpoints zonder key

De incassokosten-API en de rechtbank-API zijn openbaar. U hoeft geen account of key te hebben om ze aan te roepen.

Opdrachten

Incasso-opdrachten indienen en volgen

GET /orders

Opdrachten lijsten of op IN-nummer zoeken

API-key vereist

Geeft uw eerder ingediende opdrachten terug, nieuwste eerst, met cursorpaginatie. Handig voor reconciliatie. Filter onder andere op case_number om op het dossiernummer (IN-nummer) te zoeken.

Welke opdrachten u ziet hangt af van de instelling van uw key: óf alleen wat met deze key is ingediend, óf alle API-opdrachten van uw organisatie. U ziet nooit opdrachten van een andere opdrachtgever.

Parameters

Naam	In	Type	Toelichting
`case_number`	query	string	Filter op dossiernummer (IN-nummer), bijv. IN211543.
`reference`	query	string	Filter op uw eigen referentie.
`customer_number`	query	string	Filter op het klantnummer van een debiteur.
`creditor_id`	query	integer	Filter op de crediteur namens wie is ingediend (alleen zinvol met crediteurenbeheer; id uit GET /creditors).
`type`	query	string
`limit`	query	integer
`cursor`	query	string	De `next_cursor` uit de vorige pagina.

Antwoorden

Status	Betekenis
`200`	Gepagineerde lijst met opdrachten.
`401`	Ontbrekende of ongeldige API-key.
`429`	Rate limit overschreden. Zie de `Retry-After` header.

POST /orders

Incasso-opdracht indienen

API-key vereist

Dient een incasso-opdracht in. De verwerking is synchroon: u krijgt direct het dossiernummer (of een foutmelding) terug. Reken op 5 tot 30 seconden bij een opdracht met bijlagen; hoe meer bijlagen, hoe langer de verwerking. Stel de time-out van uw client daarom ruim in (minimaal 120 seconden) en stuur een Idempotency-Key mee, dan is opnieuw indienen na een time-out altijd veilig.

Consumenten-incasso en de WIK-aanmaning: dient u een incasso (geen pre-incasso) in tegen een particuliere debiteur (type: individual), dan is de WIK 14-dagenbrief wettelijk verplicht naast de factuur (art. 6:96 BW). Stuur die aanmaning als PDF mee en label de bijlage met document_type: "wik_letter". Ontbreekt de aanmaning, dan weigeren wij de opdracht met code wik_letter_required. Heeft de consument de 14-dagentermijn nog niet gehad, dien dan in als pre-incasso; dan versturen wij de aanmaning.

Gebruik de optionele Idempotency-Key header om te voorkomen dat een netwerk-retry dezelfde opdracht twee keer indient: bij een herhaald verzoek met dezelfde key en dezelfde inhoud krijgt u exact dezelfde response terug (met header Idempotency-Replayed: true).

Rate limiting: standaard 30 verzoeken per minuut en 500 per dag per key. Elke response op dit endpoint bevat de headers RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (seconden tot het minuutvenster reset). Bij overschrijding volgt een 429 met Retry-After.

Parameters

Naam	In	Type	Toelichting
`Idempotency-Key`	header	string	Unieke sleutel per opdracht (bijv. een UUID). Beschermt tegen dubbele indiening bij netwerk-retries.

Velden in de request body

Veld	Type	Toelichting
`type`	string	`pre-incasso`: wij sturen eerst een (kosteloze) WIK-aanmaning namens u. `incasso`: het volledige minnelijke incassotraject start direct. verplicht, keuze uit `pre-incasso` `incasso`
`reference`	string of null	Uw eigen kenmerk voor deze opdracht (komt terug in alle responses en in het dossier). max. 100 tekens
`title`	string of null	De titel/omschrijving van de vordering, idealiter in de vorm 'overeenkomst van opdracht voor ...'. Geeft u deze niet op, dan genereert onze AI er een op basis van uw omschrijving en de facturen. max. 200 tekens
`description`	string of null	Vrije omschrijving van de vordering (bijv. de geleverde dienst). Helpt onze behandelaars en de AI-titelherkenning. max. 2000 tekens
`creditor`	object of null	Optioneel, alleen met crediteurenbeheer (standaard uit; activering vooraf door nl.legal vereist, zie de Crediteuren-endpoints). Wijs de crediteur aan namens wie u indient: geef precies één van `id` (uit GET /creditors) of `reference` (uw eigen kenmerk) op. Laat u dit veld weg, dan is de opdrachtgever van uw API-key zelf de crediteur; bestaande integraties hoeven dus niets te wijzigen. Zonder geactiveerd crediteurenbeheer geeft meesturen een 403 met code `creditor_feature_disabled`.
`metadata`	object	Vrij invulbare sleutel/waarde-paren (max. 30 sleutels, sleutel max. 40 tekens, waarde max. 500 tekens). Wordt opgeslagen, in alle responses teruggegeven en als notitie in het dossier gezet. Handig om uw eigen identifiers mee te geven.
`udf_fields`	object	Optionele maatwerkvelden (UDF / flexfields) die als veld op het dossier worden gezet. U mag meerdere velden tegelijk meegeven als sleutel/waarde-paren (max. 25). Welke veldnamen voor uw account beschikbaar zijn, krijgt u van ons; gebruik exact die sleutels. Een onbekende sleutel wordt overgeslagen met de waarschuwing `udf_field_unknown`. Waarden zijn tekst, een getal, een boolean of een datum (YYYY-MM-DD); het juiste type wordt bepaald door de velddefinitie.
`debtors`	array van Debtor	De debiteur(en). Meerdere debiteuren = zelfde vordering, samen aangesproken (bijv. beide contractspartijen). Eén opdracht kan nooit losse vorderingen op verschillende debiteuren combineren. verplicht, max. 5 stuks
`invoices`	array van Invoice	verplicht, max. 50 stuks
`attachments`	array van Attachment	PDF-facturen als base64, maximaal 30 bijlagen per opdracht. Bij een consumenten-incasso telt naast elke factuur ook de WIK-aanmaning mee; met factuur+aanmaning per vordering passen er dus 15 facturen in één opdracht. Meer facturen voor dezelfde debiteur? Verdeel over meerdere opdrachten met hetzelfde `customer_number`; die worden conform de WIK in één dossier samengevoegd. Limieten op de binaire (gedecodeerde) inhoud: max. 10 MB per bestand en 25 MB totaal. Daarnaast geldt een limiet van 40 MB op de volledige base64-gecodeerde aanvraag (base64 is ca. 33% groter dan binair). Bestanden worden gevalideerd (PDF-structuur, geen wachtwoordbeveiliging) en aan het dossier toegevoegd. Elke extra bijlage verlengt de synchrone verwerkingstijd (reken op circa 1 seconde per bijlage). max. 30 stuks

Antwoorden

Status	Betekenis
`201`	Opdracht verwerkt. Bij een live-key is het dossier aangemaakt (of toegevoegd aan een bestaand open dossier, zie `case.new` en de warning `attached_to_existing_case`).
`400`	Ongeldige of lege JSON.
`401`	Ontbrekende of ongeldige API-key.
`409`	Idempotency-Key is eerder gebruikt voor een andere aanvraag.
`413`	De totale aanvraag (de volledige base64-gecodeerde JSON) is groter dan 40 MB. Let op: base64 maakt binaire bestanden circa 33% groter, dus 25 MB aan PDF's wordt ongeveer 33 MB in de aanvraag.
`415`	Content-Type is geen application/json.
`422`	Validatiefout: één of meer velden of bijlagen zijn ongeldig, OF de verplichte WIK 14-dagenbrief ontbreekt bij een consumenten-incasso (code `wik_letter_required`). Er is géén dossier aangemaakt.
`429`	Rate limit overschreden. Zie de `Retry-After` header.
`502`	Het dossiersysteem kon de opdracht niet verwerken. Probeer het later opnieuw met dezelfde Idempotency-Key.

GET /orders/{orderId}

Status van een opdracht opvragen

API-key vereist

Vraagt de actuele status van een eerder ingediende opdracht op, inclusief de live dossierstatus en het openstaande saldo.

Parameters

Naam	In	Type	Toelichting
`orderId`	path	string	Het order-ID uit de response van het indienen (bijv. `ord_b2b332c6a34ebb12`). (verplicht)

Antwoorden

Status	Betekenis
`200`	Actuele status van de opdracht.
`401`	Ontbrekende of ongeldige API-key.
`404`	Geen opdracht met dit ID voor uw account.
`429`	Rate limit overschreden. Zie de `Retry-After` header.

Stuuracties

Pauze, intrekking en betaalmeldingen op een lopend dossier

POST /orders/{orderId}/hold

Pauze aanvragen

API-key vereist

Verzoekt om het dossier te pauzeren (bijv. de debiteur belt of betwist). De API wijzigt zelf niets aan het dossier: er wordt een taak met instructies in de agenda van het dossier gezet, die een behandelaar verwerkt. Antwoordt met 202 Accepted.

Parameters

Naam	In	Type	Toelichting
`orderId`	path	string	(verplicht)

Velden in de request body

Veld	Type	Toelichting
`reason`	string	Toelichting voor de behandelaar. max. 1000 tekens

Antwoorden

Status	Betekenis
`202`	Verzoek geregistreerd als taak op het dossier.
`401`	Ontbrekende of ongeldige API-key.
`404`	Onbekende opdracht voor uw account.
`409`	Opdracht heeft geen dossier (testmodus).
`429`	Rate limit overschreden. Zie de `Retry-After` header.

POST /orders/{orderId}/withdraw

Intrekking aanvragen

API-key vereist

Verzoekt om het dossier in te trekken. Let op: intrekken kan no-cure-no-pay-kosten raken. De API plaatst een taak met instructies op het dossier; een behandelaar beoordeelt en handelt af. Antwoordt met 202 Accepted.

Parameters

Naam	In	Type	Toelichting
`orderId`	path	string	(verplicht)

Velden in de request body

Veld	Type	Toelichting
`reason`	string	max. 1000 tekens

Antwoorden

Status	Betekenis
`202`	Verzoek geregistreerd als taak op het dossier.
`401`	Ontbrekende of ongeldige API-key.
`404`	Onbekende opdracht voor uw account.
`409`	Opdracht heeft geen dossier (testmodus).
`429`	Rate limit overschreden. Zie de `Retry-After` header.

POST /orders/{orderId}/payments

Directe betaling melden

API-key vereist

Meldt dat de debiteur RECHTSTREEKS aan u (de opdrachtgever) heeft betaald. De API plaatst een taak met het bedrag en de datum op het dossier; een behandelaar boekt de betaling en het saldo + de incassokosten worden herberekend. Antwoordt met 202 Accepted.

Parameters

Naam	In	Type	Toelichting
`orderId`	path	string	(verplicht)

Velden in de request body

Veld	Type	Toelichting
`amount_cents`	integer	Het ontvangen bedrag in eurocenten. verplicht, minimaal 1
`payment_date`	string (date)	Datum van ontvangst (YYYY-MM-DD). Standaard vandaag.
`reason`	string	Toelichting (bijv. betaalwijze, kenmerk). max. 1000 tekens

Antwoorden

Status	Betekenis
`202`	Betaalmelding geregistreerd als taak op het dossier.
`401`	Ontbrekende of ongeldige API-key.
`404`	Onbekende opdracht voor uw account.
`409`	Opdracht heeft geen dossier (testmodus).
`422`	Ongeldig of ontbrekend bedrag.
`429`	Rate limit overschreden. Zie de `Retry-After` header.

Crediteuren

Crediteuren aanmaken en namens andere crediteuren indienen. Alleen beschikbaar na goedkeuring en activering door nl.legal (standaard uit); zonder activering geeft de API code creditor_feature_disabled.

GET /creditors

Toegestane crediteuren opvragen

API-key vereist

Alleen met crediteurenbeheer — deze functie staat standaard uit en moet vooraf door nl.legal voor uw API-key worden goedgekeurd en geactiveerd (via incasso@nl.legal). Zonder activering krijgt u een 403 met code creditor_feature_disabled.

Geeft de crediteuren terug namens wie u mag indienen: uw eigen organisatie (self: true, altijd bovenaan) plus alle crediteuren die onder uw account zijn aangemaakt. Gebruik het id of uw eigen reference in het veld creditor van een opdracht.

Antwoorden

Status	Betekenis
`200`	Lijst van toegestane crediteuren.
`401`	Ontbrekende of ongeldige API-key.
`403`	Crediteurenbeheer is niet geactiveerd voor uw API-key (code `creditor_feature_disabled`).
`429`	Rate limit overschreden. Zie de `Retry-After` header.
`502`	De crediteurenlijst kon niet worden opgehaald uit het dossiersysteem.

POST /creditors

Crediteur aanmaken

API-key vereist

Maakt een nieuwe crediteur aan onder uw account, bijvoorbeeld een verhuurder waarvoor u als vastgoedbeheerder incassozaken indient. De crediteur is daarna direct te gebruiken in het veld creditor bij het indienen van een opdracht.

Geef bij voorkeur een reference mee (uw eigen kenmerk): daarmee kunt u de crediteur bij het indienen selecteren zonder ons id te bewaren. De reference moet uniek zijn binnen uw account; een dubbele reference geeft een 409 met code creditor_exists.
Adres, e-mail, telefoon en IBAN zijn optioneel maar aanbevolen; het IBAN wordt gebruikt voor uitbetalingen. Ons kantoor ontvangt bij elke nieuwe crediteur een notificatie en vult zo nodig gegevens aan.
Met een test-key wordt de aanvraag volledig gevalideerd maar wordt er géén crediteur aangemaakt (id is dan null).
De Idempotency-Key header wordt ondersteund, net als bij het indienen van opdrachten.

Parameters

Naam	In	Type	Toelichting
`Idempotency-Key`	header	string	Unieke sleutel per aanvraag. Beschermt tegen dubbele aanmaak bij netwerk-retries.

Velden in de request body

Veld	Type	Toelichting
`type`	string	`business` = bedrijf, `individual` = particulier. verplicht, keuze uit `business` `individual`
`company_name`	string	Verplicht bij type `business`. max. 200 tekens
`first_name`	string of null	Voornaam (alleen bij `individual`). max. 100 tekens
`middle_name`	string of null	Tussenvoegsel (alleen bij `individual`). max. 50 tekens
`last_name`	string	Verplicht bij type `individual`. max. 100 tekens
`reference`	string of null	Uw eigen unieke kenmerk voor deze crediteur. Sterk aanbevolen: hiermee selecteert u de crediteur bij het indienen (`creditor.reference`) zonder ons id te bewaren. Moet uniek zijn binnen uw account (anders 409 `creditor_exists`). max. 100 tekens
`email`	string of null (email)
`phone`	string of null	max. 30 tekens
`iban`	string of null	IBAN van de crediteur, gebruikt voor uitbetalingen. Wordt gevalideerd op het controlegetal.
`address`	een van meerdere vormen	Optioneel; indien meegegeven gelden dezelfde eisen als bij een debiteur-adres.

Antwoorden

Status	Betekenis
`201`	Crediteur aangemaakt (of, met een test-key, volledig gevalideerd zonder aanmaak).
`400`	Ongeldige of lege JSON.
`401`	Ontbrekende of ongeldige API-key.
`403`	Crediteurenbeheer is niet geactiveerd voor uw API-key (code `creditor_feature_disabled`).
`409`	Er bestaat al een crediteur met deze reference (code `creditor_exists`), of de Idempotency-Key is eerder voor een andere aanvraag gebruikt.
`415`	Content-Type is geen application/json.
`422`	Validatiefout: één of meer velden zijn ongeldig. Er is géén crediteur aangemaakt.
`429`	Rate limit overschreden. Zie de `Retry-After` header.
`502`	Het dossiersysteem kon de crediteur niet verwerken. Probeer het later opnieuw met dezelfde Idempotency-Key.

Tools

Openbare hulpmiddelen, geen API-key vereist

POST /tools/wik

Incassokosten en rente berekenen

Openbaar, geen API-key nodig

Berekent de buitengerechtelijke incassokosten volgens het Besluit BIK (art. 6:96 BW) over een hoofdsom, en optioneel de wettelijke rente (consument) of handelsrente (zakelijk) als u een vervaldatum meegeeft. Dit endpoint vereist geen API-key en is bedoeld als hulpmiddel. De uitkomst is indicatief en geen juridisch advies.

Velden in de request body

Veld	Type	Toelichting
`amount_cents`	integer	De hoofdsom in eurocenten (bijv. € 440,86 = 44086). verplicht, minimaal 1
`debtor_type`	string	Bepaalt het rentetype: consument = wettelijke rente, zakelijk = wettelijke handelsrente. keuze uit `consumer` `business`, standaard `consumer`
`due_date`	string (date)	Optioneel. Vervaldatum van de vordering (YYYY-MM-DD); rente wordt berekend vanaf deze datum tot vandaag.
`include_vat`	boolean	Optioneel. Tel 21% btw over de incassokosten mee (relevant wanneer de opdrachtgever de btw niet kan verrekenen). standaard

Antwoorden

Status	Betekenis
`200`	De berekening.
`422`	Ongeldige of ontbrekende hoofdsom.

POST /tools/rol-router

Bevoegde kantonrechter, postbus en roldatum bepalen

Openbaar, geen API-key nodig

Geeft op basis van de woonplaats en de naam van de gedaagde de bevoegde rechtbank, de kantonzittingsplaats, het correspondentieadres (postbus), de roldag(en) en, met een betekeningsdatum, de vroegste roldatum. Deterministische lookup op de actuele zaaksverdelingsreglementen en de Wet op de rechterlijke indeling. Geen API-key vereist. Indicatief, geen juridisch advies. Bij een woonplaatsnaam die in meerdere gemeenten voorkomt wordt status 'ambiguous' met de opties teruggegeven; geef dan 'gemeente' of 'provincie' mee om te disambigueren.

Velden in de request body

Veld	Type	Toelichting
`woonplaats`	string	Woonplaats van de gedaagde (officiële BAG-woonplaatsnaam). verplicht
`naam`	string	Achternaam of bedrijfsnaam van de gedaagde. Tussenvoegsels, rechtsvorm en meerdere gedaagden worden genormaliseerd tot de maatgevende beginletter. verplicht
`betekeningsdatum`	string (date)	Optioneel (YYYY-MM-DD). Berekent de vroegste roldatum vanaf deze datum + dagvaardingstermijn.
`gemeente`	string	Optioneel. Disambigueert wanneer de woonplaatsnaam in meerdere gemeenten voorkomt.
`provincie`	string	Optioneel. Disambigueert op provincie.

Antwoorden

Status	Betekenis
`200`	Het resolutieresultaat (status: ok \| ambiguous \| not_found \| incomplete).
`422`	Ontbrekende of ongeldige velden.

Systeem

Verbinding en beschikbaarheid

GET /ping

Verbindingstest

API-key vereist

Controleer of de API bereikbaar is en (optioneel) of uw API-key geldig is. Zonder Authorization-header krijgt u authenticated: false terug.

Antwoorden

Status	Betekenis
`200`	API is bereikbaar

Modellen en velden

De objecten waaruit een opdracht is opgebouwd. Een veld dat als verplicht staat aangemerkt geldt binnen het model waarin het voorkomt.

CreateOrder

Veld	Type	Toelichting
`type`	string	`pre-incasso`: wij sturen eerst een (kosteloze) WIK-aanmaning namens u. `incasso`: het volledige minnelijke incassotraject start direct. verplicht, keuze uit `pre-incasso` `incasso`
`reference`	string of null	Uw eigen kenmerk voor deze opdracht (komt terug in alle responses en in het dossier). max. 100 tekens
`title`	string of null	De titel/omschrijving van de vordering, idealiter in de vorm 'overeenkomst van opdracht voor ...'. Geeft u deze niet op, dan genereert onze AI er een op basis van uw omschrijving en de facturen. max. 200 tekens
`description`	string of null	Vrije omschrijving van de vordering (bijv. de geleverde dienst). Helpt onze behandelaars en de AI-titelherkenning. max. 2000 tekens
`creditor`	object of null	Optioneel, alleen met crediteurenbeheer (standaard uit; activering vooraf door nl.legal vereist, zie de Crediteuren-endpoints). Wijs de crediteur aan namens wie u indient: geef precies één van `id` (uit GET /creditors) of `reference` (uw eigen kenmerk) op. Laat u dit veld weg, dan is de opdrachtgever van uw API-key zelf de crediteur; bestaande integraties hoeven dus niets te wijzigen. Zonder geactiveerd crediteurenbeheer geeft meesturen een 403 met code `creditor_feature_disabled`.
`metadata`	object	Vrij invulbare sleutel/waarde-paren (max. 30 sleutels, sleutel max. 40 tekens, waarde max. 500 tekens). Wordt opgeslagen, in alle responses teruggegeven en als notitie in het dossier gezet. Handig om uw eigen identifiers mee te geven.
`udf_fields`	object	Optionele maatwerkvelden (UDF / flexfields) die als veld op het dossier worden gezet. U mag meerdere velden tegelijk meegeven als sleutel/waarde-paren (max. 25). Welke veldnamen voor uw account beschikbaar zijn, krijgt u van ons; gebruik exact die sleutels. Een onbekende sleutel wordt overgeslagen met de waarschuwing `udf_field_unknown`. Waarden zijn tekst, een getal, een boolean of een datum (YYYY-MM-DD); het juiste type wordt bepaald door de velddefinitie.
`debtors`	array van Debtor	De debiteur(en). Meerdere debiteuren = zelfde vordering, samen aangesproken (bijv. beide contractspartijen). Eén opdracht kan nooit losse vorderingen op verschillende debiteuren combineren. verplicht, max. 5 stuks
`invoices`	array van Invoice	verplicht, max. 50 stuks
`attachments`	array van Attachment	PDF-facturen als base64, maximaal 30 bijlagen per opdracht. Bij een consumenten-incasso telt naast elke factuur ook de WIK-aanmaning mee; met factuur+aanmaning per vordering passen er dus 15 facturen in één opdracht. Meer facturen voor dezelfde debiteur? Verdeel over meerdere opdrachten met hetzelfde `customer_number`; die worden conform de WIK in één dossier samengevoegd. Limieten op de binaire (gedecodeerde) inhoud: max. 10 MB per bestand en 25 MB totaal. Daarnaast geldt een limiet van 40 MB op de volledige base64-gecodeerde aanvraag (base64 is ca. 33% groter dan binair). Bestanden worden gevalideerd (PDF-structuur, geen wachtwoordbeveiliging) en aan het dossier toegevoegd. Elke extra bijlage verlengt de synchrone verwerkingstijd (reken op circa 1 seconde per bijlage). max. 30 stuks

Debtor

Veld	Type	Toelichting
`type`	string	`business` = bedrijf, `individual` = particulier. verplicht, keuze uit `business` `individual`
`company_name`	string	Verplicht bij type `business`. max. 200 tekens
`first_name`	string of null	Voornaam (alleen bij `individual`). max. 100 tekens
`middle_name`	string of null	Tussenvoegsel (alleen bij `individual`). max. 50 tekens
`last_name`	string	Verplicht bij type `individual`. max. 100 tekens
`customer_number`	string of null	Uw unieke klantnummer voor deze debiteur. Sterk aanbevolen: bij een vervolgfactuur met hetzelfde klantnummer voegen wij de vordering conform de WIK toe aan een eventueel al openstaand dossier. max. 50 tekens
`email`	string of null (email)
`phone`	string of null	max. 30 tekens
`address`	Address	verplicht

Address

Veld	Type	Toelichting
`street`	string	verplicht, max. 150 tekens
`house_number`	string	verplicht, max. 10 tekens
`house_number_suffix`	string of null	max. 10 tekens
`postal_code`	string	Voor Nederland gevalideerd op formaat 1234 AB. verplicht, max. 12 tekens
`city`	string	verplicht, max. 100 tekens
`country`	string	ISO-3166 tweelettercode. max. 2 tekens, standaard `NL`

Invoice

Veld	Type	Toelichting
`invoice_number`	string	verplicht, max. 50 tekens
`invoice_date`	string (date)	YYYY-MM-DD, niet in de toekomst. verplicht
`due_date`	string of null (date)	Vervaldatum. Geef óf `due_date` óf `payment_term_days` op.
`payment_term_days`	integer of null	Betaaltermijn in dagen na factuurdatum; wij berekenen dan de vervaldatum. minimaal 0
`amount_cents`	integer	Openstaand bedrag incl. btw in EUROCENTEN: € 1.250,00 = 125000. Boven dit maximum (zeer grote vorderingen) krijgt u code `amount_too_high`; neem dan contact op. verplicht, minimaal 1
`description`	string of null	Optionele omschrijving van de factuur. max. 500 tekens

Attachment

Veld	Type	Toelichting
`filename`	string	Bestandsnaam (bij voorkeur eindigend op .pdf). De validatie kijkt naar de daadwerkelijke bestandsinhoud, niet naar de extensie; de opgeslagen naam wordt zo nodig met .pdf genormaliseerd. verplicht, max. 120 tekens
`content_base64`	string	De PDF als base64-string (zonder data:-prefix). verplicht
`document_type`	string of null	Type document. Label de WIK 14-dagenbrief als `wik_letter`: bij een consumenten-incasso is die verplicht (zie de beschrijving van het indien-endpoint). keuze uit `invoice` `wik_letter` `other` `null`

Order

Veld	Type	Toelichting
`id`	string	Uniek order-ID (`ord_...`). Bewaar dit voor statusopvragingen.
`object`	string
`mode`	string	keuze uit `live` `test`
`type`	string	keuze uit `pre-incasso` `incasso`
`reference`	string of null
`case`	object
`creditor`	OrderCreditor	Namens welke crediteur de opdracht is ingediend. `self: true` betekent: de opdrachtgever van de API-key zelf (de standaardsituatie). Kan ontbreken bij opdrachten van vóór de invoering van crediteurenbeheer.
`debtors`	array van object
`invoice_count`	integer
`total_amount_cents`	integer	De aangeleverde hoofdsom (som van de facturen) in eurocenten, exclusief incassokosten en rente.
`metadata`	object	De door u meegegeven metadata, ongewijzigd teruggegeven.
`udf_fields`	object	De door u meegegeven maatwerkvelden, ongewijzigd teruggegeven.
`warnings`	array van Warning	Niet-blokkerende signaleringen. De opdracht is gewoon verwerkt; u bepaalt zelf wat u met deze meldingen doet.
`created_at`	string (date-time)

OrderList

Veld	Type	Toelichting
`object`	string
`data`	array van object
`has_more`	boolean
`next_cursor`	string of null	Geef mee als `cursor` om de volgende pagina op te halen. `null` als er geen volgende pagina is.

OrderStatus

Veld	Type	Toelichting
`id`	string
`object`	string
`mode`	string	keuze uit `live` `test`
`type`	string	keuze uit `pre-incasso` `incasso`
`reference`	string of null
`case`	object
`creditor`	OrderCreditor	Namens welke crediteur de opdracht is ingediend. `self: true` betekent: de opdrachtgever van de API-key zelf (de standaardsituatie). Kan ontbreken bij opdrachten van vóór de invoering van crediteurenbeheer.
`invoice_count`	integer
`total_amount_cents`	integer	De aangeleverde hoofdsom (som van de facturen) in eurocenten, exclusief incassokosten en rente. Altijd aanwezig. Het actuele saldo inclusief kosten en rente staat in case.balance_due_cents (alleen zodra het dossier in behandeling is).
`warnings`	array van Warning	De niet-blokkerende signaleringen van het indienmoment, opnieuw teruggegeven zodat u ze ook later kunt ophalen.
`actions`	array van object	Eerder gemelde stuuracties (pauze/intrekking/betaling), nieuwste eerst.
`created_at`	string (date-time)

WikCalculation

Veld	Type	Toelichting
`object`	string
`debtor_type`	string	keuze uit `consumer` `business`
`principal_amount_cents`	integer	De ingevoerde hoofdsom in eurocenten.
`collection_costs_cents`	integer	Buitengerechtelijke incassokosten (Besluit BIK) in eurocenten, exclusief btw.
`collection_costs_vat_cents`	integer	21% btw over de incassokosten, of 0 als include_vat niet is meegegeven.
`interest`	object
`total_amount_cents`	integer	Hoofdsom + incassokosten + eventuele btw + rente, in eurocenten.
`basis`	string	Juridische grondslag en disclaimer.

WebhookEvent

Een event dat nl.legal naar uw webhook-endpoint stuurt.

Veld	Type	Toelichting
`id`	string	Uniek event-ID (evt_...).
`object`	string
`type`	string	Het type gebeurtenis. keuze uit `payment.received` `correspondence.sent` `invoice.updated` `case.updated` `case.closed` `ping`
`created_at`	string (date-time)
`data`	object

OrderAction

Veld	Type	Toelichting
`id`	string	Het order-ID waarop de actie betrekking heeft.
`object`	string
`action`	string	keuze uit `hold` `withdraw` `payments`
`status`	string	De actie is als taak geregistreerd; een behandelaar verwerkt deze.
`case`	object
`amount_cents`	integer	Alleen bij een betaalmelding.
`payment_date`	string (date)	Alleen bij een betaalmelding.
`message`	string
`created_at`	string (date-time)

OrderCreditor

Namens welke crediteur de opdracht is ingediend. self: true betekent: de opdrachtgever van de API-key zelf (de standaardsituatie). Kan ontbreken bij opdrachten van vóór de invoering van crediteurenbeheer.

Veld	Type	Toelichting
`id`	integer	Het crediteur-id (gelijk aan het id in GET /creditors).
`name`	string	Naam van de crediteur.
`self`	boolean	`true` als dit de opdrachtgever van de API-key zelf is.

CreateCreditor

Payload voor het aanmaken van een crediteur (alleen met crediteurenbeheer, zie POST /creditors).

Veld	Type	Toelichting
`type`	string	`business` = bedrijf, `individual` = particulier. verplicht, keuze uit `business` `individual`
`company_name`	string	Verplicht bij type `business`. max. 200 tekens
`first_name`	string of null	Voornaam (alleen bij `individual`). max. 100 tekens
`middle_name`	string of null	Tussenvoegsel (alleen bij `individual`). max. 50 tekens
`last_name`	string	Verplicht bij type `individual`. max. 100 tekens
`reference`	string of null	Uw eigen unieke kenmerk voor deze crediteur. Sterk aanbevolen: hiermee selecteert u de crediteur bij het indienen (`creditor.reference`) zonder ons id te bewaren. Moet uniek zijn binnen uw account (anders 409 `creditor_exists`). max. 100 tekens
`email`	string of null (email)
`phone`	string of null	max. 30 tekens
`iban`	string of null	IBAN van de crediteur, gebruikt voor uitbetalingen. Wordt gevalideerd op het controlegetal.
`address`	een van meerdere vormen	Optioneel; indien meegegeven gelden dezelfde eisen als bij een debiteur-adres.

Creditor

Een crediteur zoals teruggegeven door de Crediteuren-endpoints.

Veld	Type	Toelichting
`id`	integer of null	Het crediteur-id. Gebruik dit (of uw reference) in het veld `creditor` bij het indienen. `null` bij een test-key (er is dan niets aangemaakt).
`object`	string
`name`	string
`reference`	string of null	Uw eigen kenmerk van de crediteur.
`self`	boolean	`true` als dit de opdrachtgever van de API-key zelf is.
`warnings`	array van Warning	Alleen bij aanmaken: niet-blokkerende signaleringen.
`created_at`	string (date-time)	Alleen bij aanmaken.

CreditorList

Veld	Type	Toelichting
`object`	string
`data`	array van Creditor	Uw eigen organisatie eerst (`self: true`), daarna de onderliggende crediteuren op naam.
`has_more`	boolean
`next_cursor`	null

Warning

Veld	Type	Toelichting
`code`	string	Machine-leesbare code. keuze uit `ai_invoice_mismatch` `ai_document_mismatch` `attached_to_existing_case` `multiple_open_cases` `attachment_upload_failed` `claim_attach_failed` `debtor_address_failed` `creditor_address_failed` `creditor_iban_failed` `unknown_field` `udf_field_unknown` `wik_letter_detected` `wik_letter_incomplete` `test_mode`
`message`	string	Toelichting in het Nederlands.
`invoice_number`	string of null	Aanwezig als de warning één specifieke factuur betreft.

Problem

Foutformaat volgens RFC 9457 (application/problem+json).

Veld	Type	Toelichting
`type`	string (uri)
`title`	string
`status`	integer
`code`	string	Machine-leesbare foutcode, bijv. `validation_error`, `rate_limited`, `unauthorized`.
`detail`	string
`errors`	array van object	Bij validatiefouten (422): per veld de fout.

Webhooks

Wij sturen statuswijzigingen naar een endpoint dat u opgeeft. Elk bericht is ondertekend, zodat u kunt controleren dat het van ons komt. De opzet en het verifiëren van de handtekening staan op de handleiding.

Event	Wanneer
`event`	nl.legal stuurt een event naar uw endpoint

Aan de slag

Vraag een test-key aan en bouw de koppeling zonder dat er een dossier ontstaat. Werkt het, dan wisselt u de key om en staat u live. Gebruikt u Moneybird, dan is er een kant-en-klare Moneybird-koppeling die u zelf activeert.

API-key aanvragen