Develop with the Visma Nmbrs Developer API
The Visma Nmbrs API is a developer's interface to interact with the Visma 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 Visma Nmbrs Developer API and join our growing list of applications. Integration with Visma Nmbrs widens the scope of your application and provides an easy and effective way to reach new audiences.
- Introduction
- How to connect
- API calls
- API Implementation scenario's
- References and enumerations
- API User Template
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 Visma Nmbrs and on the different implementation scenario's, like Single Sign-On Service, Debtor Service Company Service, Employee Service see the methods below.
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.
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 Visma Nmbrs application we have a special feature called "Sandbox". Sandbox is a fully separate Visma 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 Visma 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 Visma Nmbrs is responsible for the usage of such data outside the Visma 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: Creating 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 Visma Nmbrs, you can become an integration partner. For companies that want to become an integration partner, we have prepared an action plan. See Visma Nmbrs AppStore 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 Visma 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 Visma Nmbrs environments?
- Do you want to integrate with all debtors within a Visma Nmbrs environment?
- Do you want to integrate with all companies from a debtor within Visma Nmbrs environment?
- Which user should I create for an integration?
Be aware that with our API v3 it is also necessary to connect with the users' domain. Read more on how to extract the domain and additional information here.
API calls
Methods
Determine what is the purpose of your integration. Do you want only to get information from Visma Nmbrs or do you want to insert information as well? Do you want Visma 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 Visma 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 Visma Nmbrs. Visma 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 Visma 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 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 Visma 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 Visma Nmbrs, such as, run is finished, employee information updated or end contracts.
References and enumerations
Visma Nmbrs API V3 (Latest) - Reference
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!
Comments