Nmbrs API (for developers)

Develop with the Nmbrs Developer API

The Nmbrs API is a developer's interface to interact with the Nmbrs payroll system.
This API is implemented as Soap XML Webservices and is available at https://api.nmbrs.se (if you are using a Swedish environment) and https://api.nmbrs.nl (if you are using a Dutch environment). If you are a developer, we encourage you to use the Nmbrs® Developer API and join our growing list of applications. Integration with Nmbrs® widens the scope of your application and provides an easy and effective way to reach new audiences.

Introduction

What can I do with the API?

  • Retrieve / Modify employee data including personal and payroll information. To register hours or absence for example
  • Retrieve / Modify company and debtor data. For bookkeeping, planning, schedules, dashboards etc.
  • Get reports like journals and wage components

More information on what to get out of Nmbrs and on the different implementation scenario's, like Single Sign-On Service, Debtor Service Company Service, Employee Service see the methods below. 

Usage limits 
The consumption of the API is based on a fair use policy, so at the moment no special restrictions are applied. However abusive use of the API may result in blocked access. 
You can make 150 calls per second, if this is exceeded a delay of half a second will occur. Be aware that other users might do a call at the same second.
Depending on the amount of data pulled and transferred, the time of the call may slow down. This could happen when data is fetched for many employees or for run output for large companies. 
Some operations are available to be used for bigger batches of data. When there is the need to insert data for many employees for example.

Update and changes to the API
The API is in constant evolution. All modifications are posted in our update notes. In case a change will have an impact on the current webservices description, a stage environment will be made available for developers to adapt their code. This transition phase will be available for at least one week.

Testing / Sandbox 
Next to a demo environment that can be provided to you, every environment contains a "sandbox environment". In the Nmbrs application, we have a special feature called "Sandbox". Sandbox is a fully separate Nmbrs environment with all of the previous day's data. We created this feature so that you are able to test any functionality in the Nmbrs® application without affecting any of your real data. 

Security
The API service is only available over HTTPS - Secure Socket Layer (SSL), regardless of how your account is configured. This means that the data transfer will always be encrypted. You must be a verified user to make API requests.

Regarding data security scope, the user who connects to the API and pulls data from Nmbrs is responsible for the usage of such data outside of the Nmbrs application.

Who can generate an API token?
Only top-level users on accountant and business environments can generate their own API token. For all other types of users, an API token can be generated by users with access to login settings.


Where do users with an API token have access to?
Users with an API token can use all the services and methods from our API, and users have access to all the information via our API. However, they have only access to information of the entries (debtors/companies) they have access to. This access can be set up by filtering on the user accounts. On top-level, this is done by the debtor tags. On debtor level this is done by the filtering of companies (see for more information: Giving customers access to the system

Partner Program
When you are using the API, and this integration is also interesting for the customers of Nmbrs, you can become an integration partner. For companies that want to become integration partner, we have prepared an action plan. Let us know if you want to become a partner by filling the form through the link down here:

How to connect

Authentication  and Authorization 

The API service is only available over HTTPS - Secure Socket Layer (SSL), regardless of how your account is configured.  This means that the data transfer will always be encrypted. You must be a verified user to make API requests. 
To use our API you need an email address and the API token. To get an API token you need to have an user account within a Nmbrs environment.  This means that the same filters applied in the UI (User Interface) are valid in the API. You can start the connection with an email address and a token from an existing user account or an account can be created for you.

The Level on which user account is created determines the access to API service. Questions below will help you to decide which user account you will need to integrate:

  • Do you want to integrate with one or more Nmbrs environments? 
  • Do you want to integrate with all debtors within a Nmbrs environment? 
  • Do you want to integrate with all companies from a debtor within Nmbrs environment?
  • Which user should I create for an integration?

Once you have the API you can add this to an (existing) user account.

API calls

Methods
Determine what is the purpose of your integration. Do you want only to get information from Nmbrs or do you want to insert information as well? Do you want Nmbrs to be leading system? How are you going to be in sync?
Before you start building the integration, create a functional flow that will help you understand what information you need from our system. If you know what you want to achieve you will be able to see if everything that you want is doable with API.

Here are the basic definitions to our methods for all webservices:

  • _Get - use to get data
  • _Insert - use to insert new data
  • _Update - use to change existing data
  • _Delete / _clear - use to delete data

Common fields in the methods:

  • <Datetime>
    Can be used as YYYY-MM-DD. Time can be added but will be ignored
  • <Unprotected mode>
    If the period is before the company's current period, unprotected mode flag is required, else a TWK exception is thrown. Fore more information about periods see company period
    Use 0 or false if no TWK is required. Use 1 or true if TWK is required.

 The Nmbrs API has the following Batch methods:

  • HourComponentFixed_Insert_Batch 
  • HourComponentVar_Insert_Batch 
  • WageComponentFixed_Insert_Batch 
  • WageComponentFixed_Insert_Batch_With_End 
  • WageComponentVar_Insert_Batch 

Webservices
Our Webservices are divided into four different categories. Each of them has a list of described methods and links an example SOAP call. The links underneath link to each specific category:

Numbers and ID's
Keep in mind that employee/company/debtor numbers are NOT the same as ID's.
Read the following article for more information on how to get ID's.

Additional information Report Service
The output of report service is XML structure, is cached for two hours and is the same output as in the interface. There are no debtor or company filters on the report methods, which means that these reports have to be filtered manually.

API Implementation scenario's 

Regardless the kind of integration you are building, you will have to make some decisions before integrating with Nmbrs. Nmbrs is a payroll system that has its own structure and logic behind it. Make sure you understand the different levels, and be aware that most company and employee data in Nmbrs is period based. 

Implementation Scenario's
How to use the API in case of these most common implementation scenario's: 
To create an employee that can be processed in payroll, basic information is required.

Use the time registration scenario to send wage and hour components and days for employees.

Use the absence scenario when you want to get or insert absence information for an employee. Users are free to register basic absence information or to work with absence XML

Use the HR synchronization scenario when you want to keep track or change employee information. Be aware that information that you see as HR only information, could impact and affect the payment or the payslip of an employee. 

With the SSO Service you can build an auto-login application to Nmbrs.

How to check for mutations

It's common in integration scenarios to have the need of checking for events like when data has been changed in Nmbrs, such as, run is finished, employee information updated or end contracts.

References and enumerations

Nmbrs® API V3 (Latest) - Reference

XML Reference

Nmbrs® API enumerations

API User Template

There are API templates to limit the rights to certain API calls. These template can be adjusted by the administrator user via the dashlet ‘template users’. With this templates an API user can only have access to certain calls that the client want to. The administrator user is responsible for limiting the rights to this API calls. Please see API user template!

Kommentarer

Kunskapsportal

updates

Nyheter / uppdateringar

Håll dig uppdaterad med de senaste nyheterna och uppdateringarna från Nmbrs.

Communities

Sociala medier

Håll dig uppdaterad om Visma Nmbrs senaste nyheter genom att följa oss på sociala medier och läsa vår blogg.

satisfaction

E-Learning

Vill du veta mer om Visma Nmbrs?

Our E-learning offers.

Läs mer...