Nmbrs Employments API

openapi: 3.0.3
info:
  title: Nmbrs Public REST API (HR & Payroll) Absences Employments API
  description: 'Modeled OpenAPI for the Visma Nmbrs public REST API - the current, forward-looking interface to Nmbrs HR and payroll software (Netherlands and Sweden). The REST API is served from https://api.nmbrsapp.com and is authenticated with the OAuth 2.0 Authorization Code flow (identityservice.nmbrs.com) plus a per-product subscription key sent on every request. It exposes HRIS and payroll resources - companies, employees, employments, personal and salary info, wage components, payruns, and absences - scoped by granular OAuth scopes such as employee.info, employee.employment, and employee.payment.

    HONESTY NOTE: The Nmbrs REST API reference is published as an interactive Stoplight project rather than a downloadable OpenAPI file, and the live endpoints are gated behind OAuth + a subscription key (GET https://api.nmbrsapp.com/api/companies returns 401 unauthenticated). The paths, parameters, and schemas below are MODELED from the published resource groups and the confirmed base URL / auth model; they are a faithful representation for discovery, not a byte-for-byte copy of the vendor spec. Nmbrs also operates a separate, older SOAP API (api.nmbrs.nl/soap/v3, EmployeeService / CompanyService / DebtorService) that is deprecated and scheduled to be retired on 1 March 2027 - it is described in the repository README and review, not in this REST document.'
  version: 1.0-modeled
  contact:
    name: Nmbrs Developer Portal
    url: https://developer.nmbrs.com
servers:
- url: https://api.nmbrsapp.com
  description: Nmbrs Public REST API
security:
- oauth2: []
  subscriptionKey: []
tags:
- name: Employments
  description: Employment contracts and employment history for an employee.
paths:
  /api/employees/{employeeId}/employments:
    get:
      operationId: listEmployments
      tags:
      - Employments
      summary: List employments
      description: Lists the employment contracts and history for an employee.
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: A list of employments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employment'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid OAuth token or subscription key.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 401
              message:
                type: string
                example: Access denied due to invalid subscription key or bearer token.
  schemas:
    Employment:
      type: object
      properties:
        employmentId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        contractType:
          type: string
  parameters:
    EmployeeId:
      name: employeeId
      in: path
      required: true
      description: Unique identifier of the employee.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow via identityservice.nmbrs.com.
      flows:
        authorizationCode:
          authorizationUrl: https://identityservice.nmbrs.com/connect/authorize
          tokenUrl: https://identityservice.nmbrs.com/connect/token
          scopes:
            employee.info: Read/write employee personal information
            employee.info.read: Read employee personal information
            employee.employment: Read/write employment data
            employee.employment.read: Read employment data
            employee.payment: Read/write salary and payment data
    subscriptionKey:
      type: apiKey
      in: header
      name: X-Subscription-Key
      description: Per-product subscription key generated in the Nmbrs developer portal, required on every request in addition to the OAuth bearer token.