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.nl 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.

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 APIThe 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 which 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.

SecurityThe 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 type 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 the filtering on the user accounts. On top level this is done by the debtor tags (see also: Debiteur tags aanmaken). On debtor level this is done by the filtering of companies (see for more information: Klanten toegang geven).

Partner ProgramWhen 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. See links for information on becoming an integration partner and about the application to become an integration partner.

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.

API calls

MethodsDetermine 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 periodUse 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

WebservicesOur Webservices are divided into four different categories. Each of them has a list of described methods and links an example SOAP call. The articles underneath also clarify the name of the location/dashlet in Nmbrs.

Additional information Report ServiceThe 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.

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.

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!