In January 2020, Nmbrs released a new version of it's SOAP API. Until this point, all the changes were done on the same version, v2.1. Due to big changes on the payroll engine for The Netherlands from 2019 to 2020, the Squad API realized that a new version could benefit users. v2.1 will be closed completely on 15-02-2023.

• Why a new version?
• How to use API v3?
• Retrieving the domain via the API

Why a new version?

Due to the changes on the engine for NL, some fields would need to be removed from some calls, others moved from one call to the other. You can check in details about the changes on this article Nmbrs® & 2020 API Changes. 

That is what we call breaking changes in an API. It means that our integration partners are expecting a certain list of parameters, and if we change it, the connection breaks. 

This kind of breaking change causes a lot of disturbance for partners, therefore, we would like to make the release of the changes as smooth as possible for the API. The solution for this smooth transition was to release a new version of the current API, v3.

How to use API v3? 

The main change between v2.1 and v3 is on the header. All the calls were impacted by this change.

v2.1:

<soap:Header>
   <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
   </AuthHeader>
</soap:Header>

v3:

<soap:Header>
   <AuthHeaderWithDomain xmlns="https://api.nmbrs.nl/soap/v3/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>string</Domain>
   </AuthHeaderWithDomain>
</soap:Header>

Therefore, to use API v3, the domain is an optional field. You can ignore it to facilitate the migration from v2.1 to v3. 

Retrieving the domain via the API 

For the partners that connect to many environments, there is a call available to retrieve the domain based on the Username and Token: Environment_Get. Using this call, you can fill the domain information with precise data, which is not mandatory. 

Example of return from this call: 

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Environment_GetResponse xmlns="https://api.nmbrs.nl/soap/v3/DebtorService">
      <Environment_GetResult>
        <Domain>apitesting.nmbrs.nl</Domain>
        <SubDomain>apitesting</SubDomain>
      </Environment_GetResult>
    </Environment_GetResponse>
  </soap:Body>
</soap:Envelope>

The <SubDomain>, apitesting, should be used on the header of any API v3 call on field <Domain>:

<soap:Header>
   <AuthHeaderWithDomain xmlns="https://api.nmbrs.nl/soap/v3/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>apitesting</Domain>
   </AuthHeaderWithDomain>
</soap:Header> 

Difference between v2.1 and v3

Please see this article to check out what has changed in versions.
- Differences API v2.1 and v3