Nmbrs Companies API

openapi: 3.0.3
info:
  title: Nmbrs Public REST API (HR & Payroll) Absences Companies 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: Companies
  description: Company (employer) records within a Nmbrs environment.
paths:
  /api/companies:
    get:
      operationId: listCompanies
      tags:
      - Companies
      summary: List companies
      description: Lists the companies (employers) accessible to the authenticated subscription.
      responses:
        '200':
          description: A list of companies.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        number:
          type: integer
        phase:
          type: string
  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.
  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.