openapi: 3.0.3
info:
  title: Nmbrs Public REST API (HR & Payroll) Absences Wage Components 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: Wage Components
  description: Fixed and variable wage components used in payroll.
paths:
  /api/employees/{employeeId}/wagecomponents:
    get:
      operationId: listWageComponents
      tags:
      - Wage Components
      summary: List wage components
      description: Lists fixed and variable wage components for an employee.
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: A list of wage components.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WageComponent'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWageComponent
      tags:
      - Wage Components
      summary: Add a wage component
      description: Adds a fixed or variable wage component to an employee.
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WageComponent'
      responses:
        '201':
          description: The created wage component.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WageComponent'
        '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:
    WageComponent:
      type: object
      properties:
        code:
          type: integer
        value:
          type: number
        kind:
          type: string
          enum:
          - fixed
          - variable
        period:
          type: integer
        year:
          type: integer
  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.