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.

 

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

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

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 articles underneath also clarify the name of the location/dashlet in Nmbrs.

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 V2.1 (Latest) - Reference

XML Reference

Nmbrs® API enumerations

API User Template

Volgen

Opmerkingen

Mogelijk gemaakt door Zendesk