Nmbrs API: REST-API, OAuth en subscription key uitgelegd

Wat kun je met de Nmbrs API?

Met de Nmbrs API lees je medewerkers, dienstverbanden, contracten, salarissen, afdelingen, functies, verlof en verzuim, en kun je gegevens bijwerken. HR-afdelingen en salarisadministrateurs gebruiken hem om Nmbrs te koppelen aan een HR-systeem, urenregistratie of boekhouding, en om personeelsdata naar een rapportagetool te halen.

DigiData synchroniseert met deze API personeelsdata voor HR-dashboards. Dit artikel beschrijft hoe dat in de praktijk werkt. De officiële bron is het Nmbrs-ontwikkelaarsportaal.

REST-API en SOAP-API

Nmbrs heeft twee API's. De oudere SOAP-API wordt nog door veel bestaande koppelingen gebruikt. De nieuwere REST-API werkt met JSON, OAuth 2.0 en een subscription key, en is de logische keuze voor nieuwe koppelingen. Dit artikel gaat over de REST-API.

Stap 1: registreer een app en vraag een subscription key aan

In het ontwikkelaarsportaal van Nmbrs registreer je een app voor OAuth en vraag je een subscription key aan. Die key stuur je bij elk verzoek mee; hij identificeert jouw toepassing, los van de gebruiker die inlogt.

Stap 2: inloggen met OAuth 2.0

De gebruiker logt in bij de identiteitsdienst van Nmbrs en geeft toestemming. Je wisselt de code die terugkomt in bij https://identityservice.nmbrs.com/connect/token voor een access token en een refresh token. Je client ID en secret stuur je daarbij mee als Basic-authenticatie.

• Het access token is een uur geldig.
• Met het refresh token haal je een nieuw access token op. Wordt de koppeling langere tijd niet gebruikt, dan verloopt het refresh token en moet de gebruiker opnieuw inloggen.

Stap 3: data ophalen

Elk verzoek bevat twee headers: het access token en je subscription key.

GET https://api.nmbrsapp.com/api/companies
Authorization: Bearer {access_token}
X-Subscription-Key: {subscription_key}

Nmbrs ordent gegevens per debiteur (de klant van het salarisbureau of het eigen bedrijf) en per bedrijf (de werkgever). De endpoints die je voor rapportages het meest gebruikt:

Grote lijsten komen in pagina's; vraag de volgende pagina op tot er geen meer is.

Limieten en valkuilen

• HTTP 429. Bij te veel verzoeken antwoordt Nmbrs met 429 en een Retry-After-header. Wacht precies zo lang en probeer het dan opnieuw.
• Historie. Contracten, salarissen en dienstverbanden hebben een begin- en einddatum. Voor een overzicht op een peildatum moet je zelf de geldige regel kiezen.
• Privacy. Salaris- en verzuimgegevens zijn gevoelig. Geef de koppeling alleen de rechten die nodig zijn en bewaar de data versleuteld, binnen de EU.

Wanneer je de API niet zelf hoeft te bouwen

Wil je verzuim, verloop, fte en loonkosten per afdeling zien, dan hoef je de API niet zelf te koppelen. Met de Nmbrs connector van DigiData staan medewerkers, contracten, salarissen, verlof en verzuim klaar voor Power BI, Excel en het HR dashboard. Je verzuimpercentage reken je ook snel na met de rekenhulp verzuimpercentage.

Combineer je Nmbrs met projectdata, lees dan ook hoe de Simplicate API werkt.