Nmbrs SDK: Python packages for the Nmbrs SOAP and REST API
Two open source Python packages that reduce working with the Nmbrs API to a few lines of code: nmbrs for the SOAP API and nmbrs-rest-api for the new REST API. Free to use, with tests and releases via GitHub Actions.
Works with
The question
What it was about
Anyone building an integration with Nmbrs keeps running into the same things: SOAP envelopes and sandbox settings, OAuth tokens that rotate every 30 days, pagination you have to track yourself, responses that are wrapped differently per endpoint and a 403 that does not tell you which permissions are missing. Every party solves this all over again, and every solution has bugs of its own.
What we built
The solution
nmbrs (SOAP): one Python package for the five services of the Nmbrs SOAP API (Debtor, Company, Employee, Single Sign-On and Report), with two ways of signing in, sandbox mode by default so you never accidentally work on production, and its own error classes so your code knows what went wrong.
nmbrs-rest-api (REST): all 84 read endpoints of the new REST API, generated from the official OpenAPI specification. The package handles OAuth 2.0 from start to finish (signing in, refreshing before expiry, storing rotating refresh tokens safely), follows pagination automatically, caches per object and per filter, and translates a 403 into the scope you are missing.
Both packages have a test suite and are built and published automatically via GitHub Actions. Because the Nmbrs SOAP API is retired on 1 March 2027, the import names are deliberately different: you can install both side by side and migrate step by step.
In brief
For whom
Developers and software vendors building an integration with Nmbrs
Role of LK Software
Design, development, documentation and maintenance
Packages
Nmbrs SOAP API and Nmbrs REST API
Status
In use, available on PyPI and GitHub
How it works
In four steps
01
Install
pip install nmbrs or pip install nmbrs-rest-api. Python 3.10 or higher, no other dependencies on your side.
02
Sign in
SOAP: username and token or domain. REST: give consent once in the browser, after that everything runs on the stored refresh token.
03
Read data
api.companies(), employee.contracts(year=2026): readable methods instead of SOAP calls or loose HTTP requests.
04
Handle errors
Every error is its own Python exception, with an explanation of what to do. Tokens are stripped from error messages so you can log them safely.
Result
What it delivers
An Nmbrs integration no longer starts from zero: authentication, pagination and error handling are solved and tested.
Open source under the MIT and Apache 2.0 licences, so free to use in commercial software.
The same knowledge is available as training: in one day we set up your integration together, see Training.
More projects
Also interesting
Payroll Check Tool
A checking tool that tests a payroll administration in Nmbrs on 100 points and shows straight away what is not right yet: from contracts and personal details to wage tax settings and wage codes.
View projectPension filing taxi & transport
Pensioenfonds Vervoer, the Dutch pension fund for the transport sector, has no automatic integration with payroll packages, so transport companies with many on-call workers process dozens of changes by hand every month.
View projectLoket → Nmbrs document converter
Anyone switching to Nmbrs takes the payroll data along, but not automatically the documents per employee.
View projectWant something similar?
Describe your situation and the packages you use in a few sentences. Within one working day you get an honest estimate of approach, lead time and costs.