Nmbrs API-migratie: je SOAP-koppeling stopt

Op 1 maart 2027 stopt Nmbrs definitief met de SOAP-API. Draait er een Nmbrs-koppeling die salarisdata doorzet naar je boekhouding, BI-dashboard of roosterpakket, dan valt die integratie op die datum stil — tenzij je op tijd migreert naar de nieuwe REST-API. Bij CleverTech AI zien we dat veel bedrijven en kantoren niet eens weten dat ze een SOAP-koppeling draaien: die is jaren geleden ingericht en werkt gewoon. Precies daarom is dit risicovol.

Hieronder krijg je de harde deadline, een inventarisatie die je binnen een uur doet, het migratiepad naar REST en de afweging tussen zelf migreren en uitbesteden. We bouwen regelmatig API-koppelingen op maat; in onze gids over maatwerk software staat het bredere plaatje, hier zoomen we in op deze specifieke deadline.

Wat verandert er precies aan de Nmbrs API?#

Nmbrs stopt op 1 maart 2027 met de ondersteuning van de SOAP-API (versie 3.0). Vanaf die datum is de REST-API (versie 1.0) de enige koppelmethode. Bestaande integraties moeten vóór die datum zijn overgezet, anders stopt de datastroom tussen Nmbrs en je gekoppelde systemen (Nmbrs developerdocumentatie{target="_blank" rel="noopener noreferrer"}, geraadpleegd juli 2026).

Concreet betekent dit: elke koppeling die nu via SOAP salarisstroken, medewerkergegevens, loonjournaalposten of verlofsaldi ophaalt of wegschrijft, moet opnieuw worden gebouwd op de REST-API. Dat is geen instelling die je omzet. Het is een technische verbouwing van de koppeling zelf, inclusief een andere manier van inloggen.

De datum staat vast en is niet nieuw: Nmbrs bouwt de REST-API al sinds een bèta-release in maart 2021 stap voor stap uit (Nmbrs Developer Portal{target="_blank" rel="noopener noreferrer"}). Wat nieuw is, is dat de uitfasering nu een harde einddatum heeft. Uitstellen tot begin 2027 is geen strategie — het is een risico.

Waarom Nmbrs de SOAP-API uitfaseert#

Nmbrs vervangt SOAP door REST vooral om veiligheids- en beheersredenen. De oude SOAP-API werkt met een API-token dat je letterlijk in je koppeling plakt; de REST-API gebruikt OAuth 2.0, waarbij een gebruiker via een toestemmingsscherm expliciet rechten toekent aan een applicatie (Nmbrs, Building a Nmbrs integration{target="_blank" rel="noopener noreferrer"}, 2026).

Het verschil is fundamenteel. Bij een API-token deelt de klant in feite een generieke sleutel die overal toegang toe geeft. Bij OAuth 2.0 vraagt de applicatie specifieke scopes aan — bijvoorbeeld alleen lezen van loongegevens, niet schrijven — en ziet de gebruiker precies wat hij toestaat (Nmbrs Developer Portal, Scopes{target="_blank" rel="noopener noreferrer"}, 2026). Voor salarisdata, een van de gevoeligste datasoorten die er zijn, is dat een logische stap.

Daarnaast is REST simpelweg de moderne standaard. SOAP is XML-zwaar, omslachtig en wordt breed uitgefaseerd — niet alleen bij Nmbrs, maar ook bij grote platforms als NetSuite en de Microsoft-advertentie-API. Nmbrs is dus geen uitzondering, en dat betekent dat kennis en tooling voor REST-koppelingen ruim beschikbaar zijn.

Stopt jouw koppeling ook? Zo herken je een SOAP-integratie#

Je koppeling stopt als die via de SOAP-API loopt — en de eerlijke waarheid is dat de meeste bestaande Nmbrs-koppelingen dat doen. Alles wat vóór 2022 is ingericht draait vrijwel zeker op SOAP, omdat de REST-API toen nog nauwelijks functionaliteit had. Twijfel je? Dan is dat op zich al een signaal om te inventariseren.

Er zijn drie praktische herkenningspunten. Werkt je koppeling met een API-token dat een gebruiker in Nmbrs heeft aangemaakt (Beheer, API-token)? Dan is het SOAP. Verwijst de technische documentatie of de leverancier naar endpoints op api.nmbrs.nl met woorden als SoapService of WSDL? SOAP. Loopt de aanmelding daarentegen via een toestemmingsscherm van Nmbrs waar je een applicatie autoriseert? Dan zit je waarschijnlijk al op REST.

Denk hierbij niet alleen aan de voor de hand liggende koppeling met je boekhoudpakket. Ook koppelingen naar verzuimsystemen, HR-dashboards, planningstools, pensioenaanleveringen en zelfmaakte Excel- of Power BI-exports kunnen op de SOAP-API leunen. Één stilgevallen koppeling die de loonjournaalpost niet meer doorzet, betekent handmatig overtypen in je administratie.

Hoe inventariseer je al je Nmbrs-koppelingen?#

Begin met een simpele inventarisatie voordat je iets technisch doet. De meeste tijd in een migratie gaat niet naar het bouwen, maar naar het achterhalen wélke koppelingen er zijn en wie ervan afhankelijk is. Hiervoor gebruiken we bij CleverTech AI een vaste aanpak: de koppel-inventarisatie in vier stappen.

Stap 1: inventariseer de tokens#

Log in bij Nmbrs en kijk onder Beheer welke API-tokens actief zijn. Elk actief token wijst op minimaal één SOAP-koppeling. Noteer per token wanneer het is aangemaakt en door wie.

Stap 2: breng de datastromen in kaart#

Bepaal per koppeling welke data eruit gaat (salarisstroken naar de boekhouding, medewerkers naar het HR-systeem) en welke kant op. Teken het desnoods letterlijk: Nmbrs in het midden, pijlen naar elk systeem.

Stap 3: benoem de eigenaar#

Wie merkt het als deze koppeling stopt? De salarisadministrateur, de controller, een externe leverancier? Zonder eigenaar valt een koppeling tussen wal en schip — precies daar ontstaan de verrassingen in 2027.

Stap 4: bepaal de bouwer#

Is de koppeling gemaakt door een softwareleverancier (dan ligt de migratie deels bij hen), of is het maatwerk dat intern of door een partij als CleverTech AI is gebouwd? Dit bepaalt wie aan zet is.

Na deze vier stappen heb je een lijst waarmee je gericht kunt plannen in plaats van in paniek te schieten in februari 2027.

SOAP versus REST: het verschil voor jouw integratie#

Het praktische verschil zit in authenticatie, toegangsniveau en limieten — niet alleen in de techniek eronder. Onderstaande tabel vat de punten samen die bepalen hoe zwaar jouw migratie wordt.

Bron: Nmbrs, Building a Nmbrs integration (2026).

De belangrijkste regels om te onthouden zijn de derde en de vijfde. Het toegangsniveau raakt vooral accountantskantoren (zie de volgende sectie), en de rate limits kunnen koppelingen raken die in korte tijd veel data ophalen — denk aan een nachtelijke synchronisatie van alle medewerkers. Wat onder SOAP zonder nadenken werkte, moet onder REST soms slimmer worden opgebouwd met paginering.

De valkuil: accountant-logins werken nog niet op REST#

Dit is de vervelendste verrassing van de hele migratie: de REST-API werkt op dit moment niet voor accountant-logins. Authenticatie kan alleen op klant- of bedrijfsniveau (debtor). Wie als accountantskantoor gewend was één koppeling voor alle klanten te draaien, kan dat model niet één-op-één overzetten (Nmbrs, Building a Nmbrs integration{target="_blank" rel="noopener noreferrer"}, 2026).

Voor salarisverwerkers en administratiekantoren is dit geen detail maar een architectuurvraag. Een SOAP-koppeling op accountantniveau die tientallen of honderden klantadministraties bediende, wordt onder REST een reeks autorisaties per klant. Dat betekent meer OAuth-toestemmingen beheren en mogelijk een andere opzet van je integratie.

Onze eerlijke inschatting: begin hier zo vroeg mogelijk mee, want juist deze kantoren hebben het meeste uit te zoeken. Nmbrs ontwikkelt de REST-API scenario voor scenario door op basis van wat partners nodig hebben, dus controleer regelmatig of de functionaliteit die jij mist inmiddels beschikbaar is. Kantoren die hun administratie automatiseren lopen hier het eerst tegenaan — en hebben ook het meeste te winnen bij een doordachte herbouw.

Hoe ziet het migratiepad van SOAP naar REST eruit?#

Het migratiepad is in de kern een herbouw van de koppeling op een nieuwe basis, met een parallelle testfase voordat je overschakelt. In grote lijnen doorloop je vier fasen, waarbij je de oude koppeling pas uitzet als de nieuwe bewezen werkt.

Fase 1: registreer een applicatie#

Maak in het Nmbrs Developer Portal een OAuth-applicatie aan en vraag de scopes aan die jouw koppeling nodig heeft. Dit vervangt het oude API-token.

Fase 2: herbouw de datastromen#

Zet elke SOAP-aanroep om naar het REST-equivalent. Let op verschillen in datamodel en op paginering, want REST levert grote datasets in delen aan.

Fase 3: test parallel#

Laat de oude en nieuwe koppeling een periode naast elkaar draaien en vergelijk de output. Klopt de loonjournaalpost uit REST met die uit SOAP? Pas als dat consistent klopt, ga je door.

Fase 4: schakel over en ruim op#

Zet de koppeling live op REST, monitor een aantal cycli en trek daarna pas het oude API-token in. Documenteer wat je hebt gebouwd, zodat de volgende beheerder het begrijpt.

Deze aanpak werkt of je nu een simpele boekhoudkoppeling hebt of een complex maatwerktraject. Het verschil zit in de omvang van stap 2 — en die omvang ken je pas na een goede inventarisatie.

Zelf migreren of uitbesteden?#

Of je zelf migreert hangt af van wie de koppeling bouwde en hoeveel er van afhangt. Draait je koppeling via een standaard softwareleverancier (bijvoorbeeld een boekhoud- of HR-pakket met een kant-en-klare Nmbrs-integratie), dan is het meestal hún taak om te migreren. Jouw actie is dan simpel: vraag de leverancier schriftelijk om een tijdlijn.

Wordt het maatwerk of intern beheer, dan is onderstaande afweging bruikbaar.

De vuistregel: hoe kritischer de data en hoe complexer het toegangsmodel, hoe eerder je expertise inschakelt. Salarisdata is geen plek om te leren op de nieuwe API. CleverTech AI adviseert bedrijven zonder eigen OAuth-ervaring om in elk geval de inventarisatie en het testplan te laten begeleiden, ook als het bouwen deels intern gebeurt. Besteed je de migratie uit, dan werken wij met een vaste prijs — een koppeling bouwen start vanaf €5.000; wat een Nmbrs-migratie in jouw situatie kost, staat op onze pagina over Nmbrs- en Visma-koppelingen. Wil je zulke koppelingen structureel goed opzetten, kijk dan naar API-koppelingen en systeemintegratie en het automatiseren van de bijbehorende workflows.

Wanneer moet je beginnen?#

Begin nu met inventariseren, ook al ligt de deadline in 2027. De reden is simpel: de inventarisatie kost weinig tijd, maar levert de informatie op waarmee je kunt inschatten hoeveel werk de migratie is. Zonder die inschatting kun je niet plannen, geen leverancier aanspreken en geen budget reserveren.

Een realistische planning ziet er zo uit: inventariseer nu, plan de migratie in de tweede helft van 2026 of vroeg 2027 in, en houd een marge van enkele maanden vóór 1 maart 2027 voor de parallelle testfase. Accountantskantoren met het login-vraagstuk zetten die planning het beste nog vooraan. Wie wacht tot de laatste weken, migreert onder druk — en juist bij salarisdata wil je dat niet.

Wil je weten hoe je Nmbrs-koppeling ervoor staat en wat de overstap in jouw geval betekent? Begin met de inventarisatie uit dit artikel, bekijk ons aanbod voor Nmbrs- en Visma-koppelingen met vaste prijzen, of reken in twee minuten een prijsindicatie door voor jouw migratie. En voor het bredere plaatje rond koppelingen en digitalisering blijft onze gids over maatwerk software het startpunt.