Building a Nmbrs integration
-
Integration process
-
Nmbrs Need-to-know
-
REST API Need-to-know
-
SOAP API Need-to-know
Integration process
We have set up several steps to ensure you can become an integration partner.
Step 1: Nmbrs App Store
If you havenʼt done so already, it is crucial to sign up to get started. You can do so through the Nmbrs App Store.
Step 2: Create a Nmbrs environment
Create your own Nmbrs demo environment via the Nmbrs sign-up page. When creating your Nmbrs test environment please use extdev-(AppName) as your company and domain name. When filling out the form, it is crucial to use the affiliate code: DEMO. That way, you can use it as a test domain partner, and the demo environment wonʼt expire in 30 days.
Please let us know if you would like to have demo companies placed within your environment.
Step 3: Discover the API and Nmbrs architecture
It is important to become familiar with the Nmbrs architecture and understand a few basic concepts. There are two APIs you can use. A REST and a SOAP API.
The REST API is our newest API. This API is documented here: REST API*. You can also get started with the REST API in the developer portal.
More extensive information about the SOAP API can be found here. Please see this page to see all endpoints available. In the long run, we will stop supporting the SOAP API.
* Be aware that the authentication with the REST API can only be done on debtor level, not with a master login in a Nmbrs Accountant environment.
Step 4: Support
You will have full access to our Support team while building the integration. For any questions that come up during building, please send in a ticket through our Knowledge Base. To directly get in touch with our API specialists, make sure to select the ticket form ʻIntegratiepartnerʼ.
Step 5: Demo
Once you finish the integration, it needs to be validated. This can be done through sharing a video showing what the integration looks like and how it works for the end-user, and filling in the 'Ready-to-demo form'. The video should contain:
- The set-up of the integration (activation, consent flow/insert API token)
- How does the integration work on a daily basis, show own product settings + Nmbrs fields that are imported or extracted.
- How and when is data synced? Is this based on triggers, scheduling or manual actions?
Make sure to fill the 'Ready-to-demo form'.
Requests for a Production subscription to the REST API (higher rate limits) are only accepted after a succesful demo.
Step 6: App Store listing
Once your integration is validated and you build the integration to your application as a generic solution, your integration will be listed on our Nmbrs App Store. Please see the ʻNeed-to-knowʼ section for the specific App Store requirements.
Nmbrs Need-to-know
When you are on route to building a Nmbrs integration there are a couple of matters that are important to know. We are happily sharing them with you.
API Documentation
Check out our API documentation as well as the in-depth explanation of the Nmbrs architecture:
Period Based
Before you start building, it is good to know that Nmbrs operates period-based. This means that the payroll period for January is referred to as period 1. There are three types of payroll periods that Nmbrs works with; month, 4 weeks, and week.
Weekly Updates
We aim to always improve our product, which is why we have a weekly update, usually planned every Wednesday at 20:00 CEST. On our status page you are able to see when we scheduled this update, when it has finished, and any other occasions where Nmbrs might be off-line.
Webhooks
In Nmbrs you can work with webhooks. This ensures that your integration receives a trigger when a specific action has been performed, which your integration is dependent on. You can read more about it here.
App Store Requirements
In order to get listed on our App Store, the integration should have the following requirements:
- The software that you connect to Nmbrs should be your own application
- The API token should be inserted within your application by the end-user
- Promote Nmbrs on your website by maintaining an active hyperlink to www.nmbrs.com .
- The integration should be generic, for all types of customers to use (SOAP API only)
- The API token should be safely stored in your app (SOAP API only)
Integration scenarios
To start building an integration with Nmbrs, we created several scenarios to explain best practice functional designs, including API calls.
REST API Need-to-know
Which user to create in Nmbrs to set up the integration?
The REST API is currently not available for accountant logins. To authenticate as a user, it is necessary to have a client login or company login. These types of logins are created at the so-called debtor level.
OAuth 2.0 Authorization
REST API authentication is done using the standard OAuth 2.0 Authorization Code Flow. The standard flow is the most well known OAuth 2.0 flow and typically used by web server applications. It requires your app to securely use and store a client secret.
Development vs. production subscription
The product tab in the Developer portal describes two subscription types. The development subscription is available for everyone wanting to integrate with the Nmbrs platform and used during the development. No approval from Nmbrs is needed to get access to the API. The production subscription is only approved after a successful demo and the listing is published on the Nmbrs App Store.
Scopes
Part of the OAuth 2.0 Authorization is selecting the right scopes for carrying out the intended purpose of the integration. The calling application will request authorization from the Nmbrs user to access the requested scopes, and the user will approve or deny the request.
API Usage
The number of requests made with the REST API is limited by the chosen product in the developer portal. The number of available requests is lower when developing the integration. For more information about API usage check out our API terms of use.
Versioning
The REST API version 1.0 is the newest version of the REST API.
SOAP API Need-to-know
Which user to create in Nmbrs to set up an integration?
To create the right user to set up an integration it is important to know what access the integration needs. It could be access for the entire Visma Nmbrs environment for all debtors in the Accountant product, but it could also be one company in a Business product. Check out this support article to create the right login for your integration.
API Token requirements
To set up the integration, the API token is needed from the Nmbrs environment. It is important to ensure the end-user can insert their username and API token in your platform to activate the integration. This way we ensure that the token is safely inputted and stored instead of being transferred by mail or other less-safe possibilities.
Active web services
In order to be able to access the right web services through the API, it is important to ensure these web services are set to ʻactiveʼ in the user template. Read more on how to activate the access in this article. Note: these web services are only relevant when using the SOAP API.
Background calls
In the SOAP API we work with background API calls to get the most reliable response on big data. To know how to execute these background calls see our support article.
API usage
We do not limit the number of requests you make with the SOAP API. We do believe in a fair-use-policy, check out our API terms of use for more information.
Versioning
The SOAP API version 3.0 is the newest version available of the SOAP API.
Get in touch
Our compliance officer and the support team are happy to help you with your questions.
