openapi: 3.0.3
info:
  title: Nmbrs Public REST API (HR & Payroll) Absences Employees 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: Employees
  description: Employee records and their personal / HR information.
paths:
  /api/companies/{companyId}/employees:
    get:
      operationId: listCompanyEmployees
      tags:
      - Employees
      summary: Get employee list
      description: Lists the employees belonging to the given company.
      parameters:
      - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: A list of employees.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/employees/{employeeId}:
    get:
      operationId: getEmployee
      tags:
      - Employees
      summary: Get an employee
      description: Retrieves a single employee by identifier.
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: An employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '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.
  parameters:
    CompanyId:
      name: companyId
      in: path
      required: true
      description: Unique identifier of the company.
      schema:
        type: string
    EmployeeId:
      name: employeeId
      in: path
      required: true
      description: Unique identifier of the employee.
      schema:
        type: string
  schemas:
    Employee:
      type: object
      properties:
        employeeId:
          type: string
        personalInfo:
          $ref: '#/components/schemas/PersonalInfo'
    PersonalInfo:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        emailAddress:
          type: string
          format: email
  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.