Visma Employees API

openapi: 3.2.0
info:
  title: Visma Employees API
  contact:
    email: api@spiris.se
  version: '1.0'
  description: 'Operations tagged Employees across 2 of this provider''s published API definitions: visma-payroll-api-v1-openapi-original.json, visma-payroll-api-v2-openapi-original.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://vlsapi.vismaonline.com/
tags:
- name: Employees
  description: Managing employees in your company's payroll system. You can retrieve employee information including personal details, contract status, employment agreements, work schedules, holiday balances, and time bank values.
paths:
  /v1/employees:
    get:
      tags:
      - Employees
      summary: Get all employees
      description: 'Retrieves a paginated list of all employees in the company.

        You can use query options ($filter, $select, $orderby, $top, $skip) to customize your request.

        The endpoint includes both active and draft employees but excludes deleted employees. Limited employees are also included in the results.'
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponseOfEmployeeApi'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: getV1Employees
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
  /v1/employees/{employeeId}:
    get:
      tags:
      - Employees
      summary: Get employee by id
      description: 'Retrieves a specific employee by their unique identifier. The response includes comprehensive employee information such as personal details, contact information, address, employment status and other associated information.

        You can use OData query options like `$select` to retrieve only specific fields from the employee record.'
      parameters:
      - name: employeeId
        in: path
        description: Id of the employee
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeApi'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: getV1EmployeesByEmployeeId
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
  /v2/employees:
    get:
      tags:
      - Employees
      summary: Get all employees
      description: 'Retrieves a paginated list of all employees in the company.

        You can use query options ($filter, $select, $orderby, $top, $skip) to customize your request.

        The endpoint includes both active and draft employees but excludes deleted employees. Limited employees are also included in the results.'
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponseOfEmployeeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: getV2Employees
      x-operation-id-source: derived
    post:
      tags:
      - Employees
      summary: Create employee
      description: Create employee in this company.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateEmployeeRequest'
      responses:
        '201':
          description: Resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmployeeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: postV2Employees
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
  /v2/employees/{employeeId}:
    get:
      tags:
      - Employees
      summary: Get employee by id
      description: 'Retrieves a specific employee by their unique identifier. The response includes comprehensive employee information such as personal details, contact information, address, employment status and other associated information.

        You can use OData query options like `$select` to retrieve only specific fields from the employee record.'
      parameters:
      - name: employeeId
        in: path
        description: Id of the employee
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: getV2EmployeesByEmployeeId
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
  /v2/employees/{employeeId}/workschedules:
    post:
      tags:
      - Employees
      summary: Create employee work schedule
      description: Add a work schedule to an employee.
      parameters:
      - name: employeeId
        in: path
        description: Id of employee
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddWorkScheduleToEmployeeRequest'
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddWorkScheduleToEmployeeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: postV2EmployeesByEmployeeIdWorkschedules
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
  /v2/employees/{employeeId}/agreements:
    post:
      tags:
      - Employees
      summary: Create employee agreement
      description: Add an agreement to an employee.
      parameters:
      - name: employeeId
        in: path
        description: Id of employee
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddAgreementToEmployeeRequest'
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAgreementToEmployeeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonExtendedBadRequest'
      operationId: postV2EmployeesByEmployeeIdAgreements
      x-operation-id-source: derived
    servers:
    - url: https://vlsapi.vismaonline.com/
components:
  schemas:
    PaginatedResponseOfEmployeeApi:
      required:
      - Data
      - Meta
      type: object
      properties:
        Meta:
          allOf:
          - $ref: '#/components/schemas/CommonPaginationMetadata'
        Data:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeApi'
      additionalProperties: false
    CommonPaginationMetadata:
      required:
      - CurrentPage
      - PageSize
      - ServerTimeUtc
      - TotalNumberOfPages
      - TotalNumberOfResults
      type: object
      properties:
        CurrentPage:
          type: integer
          description: The current page number
          format: int32
        PageSize:
          type: integer
          description: The number of results per page
          format: int32
        TotalNumberOfPages:
          type: integer
          description: The total number of pages available
          format: int32
        TotalNumberOfResults:
          type: integer
          description: The total number of results available for the query
          format: int32
        ServerTimeUtc:
          type: string
          description: The date-time notation as defined by RFC 3339, section 5.6  2017-07-21T17:32:28Z
          format: date-time
      additionalProperties: false
    EmployeeWorkingScheduleApi:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the employee working schedule assignment
          format: uuid
        WorkScheduleId:
          type: string
          description: Reference to the work schedule definition
          format: uuid
        WorkWeekCycleStart:
          type:
          - integer
          - 'null'
          description: Starting week number in the work week cycle, if the schedule uses a rotating pattern
          format: int32
        Name:
          type:
          - string
          - 'null'
          description: Name of the work schedule
        IsDeleted:
          type: boolean
          description: Indicates whether the employee working schedule is marked as deleted
        ActiveSince:
          type: string
          description: Date when this work schedule became active for the employee
          format: date-time
      additionalProperties: false
    CommonError:
      type: object
      properties:
        Field:
          type:
          - string
          - 'null'
        ErrorCode:
          type:
          - string
          - 'null'
        Message:
          type:
          - string
          - 'null'
        Key:
          type:
          - string
          - 'null'
      additionalProperties: false
    EmployeeAgreementApi:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the employee agreement assignment
          format: uuid
        Name:
          type:
          - string
          - 'null'
          description: Name of the agreement
        AgreementId:
          type: string
          description: Reference to the agreement definition
          format: uuid
        ActiveSince:
          type: string
          description: Date when this agreement became active for the employee
          format: date-time
        HasConfidenceTime:
          type: boolean
          description: Indicates whether the agreement includes confidence time provisions
        IsDeleted:
          type: boolean
          description: Indicates whether the employee agreement is marked as deleted
      additionalProperties: false
    EmployeeApi:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the employee
          format: uuid
        VismaEmployeeId:
          type:
          - string
          - 'null'
          description: Unique identifier of the employee in the Visma system
          format: uuid
        FirstName:
          type:
          - string
          - 'null'
          description: Employee's first name
        LastName:
          type:
          - string
          - 'null'
          description: Employee's last name
        IdentificationNumber:
          type:
          - string
          - 'null'
          description: Personal identification number (personnummer) of the employee
        EmployeeNumber:
          type:
          - string
          - 'null'
          description: Employee number assigned by the company
        PhoneMobile:
          type:
          - string
          - 'null'
          description: Employee's mobile phone number
        PhoneWork:
          type:
          - string
          - 'null'
          description: Employee's work phone number
        EmailWork:
          type:
          - string
          - 'null'
          description: Employee's work email address. Can be null
        PrimaryAddress:
          type:
          - string
          - 'null'
          description: Primary street address line of the employee's residence
        SecondaryAddress:
          type:
          - string
          - 'null'
          description: Secondary address line (apartment number, floor, etc.)
        City:
          type:
          - string
          - 'null'
          description: City of the employee's residence
        Zip:
          type:
          - string
          - 'null'
          description: Postal code of the employee's residence
        Country:
          type:
          - string
          - 'null'
          description: Country of the employee's residence
        UsesHolidayDays:
          type: boolean
          description: Indicates whether the employee uses holiday days
        UsesPayslip:
          type: boolean
          description: Indicates whether the employee receives digital payslips
        UsesWorkingTimeAccountOrReserve:
          type: boolean
          description: Indicates whether the employee uses working time account or reserve functionality
        EmployeeCategory:
          type:
          - integer
          - 'null'
          description: 'Employee category<br/>Possible values: 0 - WhiteCollar, 1 - BlueCollar'
          format: int32
        TypeOfPayment:
          type: integer
          description: 'Salary type for the employee<br/>Possible values: 1 - Monthly, 2 - Hourly'
          format: int32
        Type:
          type: integer
          description: 'Employee type. Only regular employees can use shortcuts<br/>Possible values: 0 - Regular, 1 - Limited'
          format: int32
        ContractEndDate:
          type:
          - string
          - 'null'
          description: The end date of the employee's contract, if applicable
          format: date-time
        LastLockedDeviationDate:
          type:
          - string
          - 'null'
          description: Last date when deviations were locked for this employee
          format: date-time
        ModifiedUtc:
          type: string
          description: Timestamp when the employee record was last modified (UTC)
          format: date-time
        HolidayRemainingUnpayed:
          type:
          - number
          - 'null'
          description: Remaining unpaid holiday days in decimal format
          format: double
        HolidayRemainingSaved:
          type:
          - number
          - 'null'
          description: Remaining saved holiday days in decimal format
          format: double
        HolidayRemainingPayed:
          type:
          - number
          - 'null'
          description: Remaining paid holiday days in decimal format
          format: double
        HolidayRemainingAdvance:
          type:
          - number
          - 'null'
          description: Remaining advance holiday days in decimal format
          format: double
        CompensationTimeBalanceInMinutes:
          type:
          - number
          - 'null'
          description: Compensation time balance in minutes
          format: double
        TimeReserveType:
          type:
          - integer
          - 'null'
          description: 'Type of time bank reserve<br/>Possible values: 1 - WorkingTimeReserve, 2 - WorkingTimeAcount'
          format: int32
        TimeReserveInMinutes:
          type:
          - number
          - 'null'
          description: Amount of minutes accumulated in the time bank reserve
          format: double
        UsesVLAFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses VLA (Visma Leave Application)
          format: date-time
        UsesVLA:
          type: boolean
          description: Indicates whether the employee uses VLA (Visma Leave Application)
        UsesCompanyExpenseFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses company expense management
          format: date-time
        EmployeeAgreements:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EmployeeAgreementApi'
          description: List of agreements associated with the employee
        EmployeeWorkingSchedules:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EmployeeWorkingScheduleApi'
          description: List of working schedules associated with the employee
        IsDeleted:
          type: boolean
          description: Indicates whether the employee is marked as deleted
      additionalProperties: false
    CommonExtendedBadRequest:
      type: object
      properties:
        ErrorCode:
          type: integer
          format: int32
        DeveloperErrorMessage:
          type:
          - string
          - 'null'
        ErrorId:
          type: string
          format: uuid
        Errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CommonError'
      additionalProperties: false
    AddWorkScheduleToEmployeeRequest:
      required:
      - ActiveSince
      - WorkScheduleId
      - WorkWeekCycleStart
      type: object
      properties:
        WorkScheduleId:
          type: string
          description: Unique identifier of the work schedule to assign to the employee
          format: uuid
        WorkWeekCycleStart:
          type: integer
          description: Starting week number in the work week cycle. Default 0 when the schedule only has one work week. If the schedule has more than one week, set the start week for the employee
          format: int32
        ActiveSince:
          type: string
          description: Date from which the work schedule becomes active for the employee
          format: date-time
      additionalProperties: false
    AddAgreementToEmployeeResponse:
      type: object
      properties:
        AgreementId:
          type: string
          description: Unique identifier of the agreement that was assigned
          format: uuid
        Success:
          type: boolean
          description: Indicates whether the agreement was successfully added to the employee
        ValidationError:
          allOf:
          - $ref: '#/components/schemas/CommonValidationError'
          description: Validation error details if the operation was not successful
      additionalProperties: false
    EmployeeResponse:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the employee
          format: uuid
        FirstName:
          type:
          - string
          - 'null'
          description: Employee's first name
        LastName:
          type:
          - string
          - 'null'
          description: Employee's last name
        IdentificationNumber:
          type:
          - string
          - 'null'
          description: Personal identification number (personnummer) of the employee
        EmployeeNumber:
          type:
          - string
          - 'null'
          description: Employee number assigned by the company
        PhoneMobile:
          type:
          - string
          - 'null'
          description: Employee's mobile phone number
        PhoneWork:
          type:
          - string
          - 'null'
          description: Employee's work phone number
        EmailWork:
          type:
          - string
          - 'null'
          description: Employee's work email address. Can be null
        PrimaryAddress:
          type:
          - string
          - 'null'
          description: Primary street address line of the employee's residence
        SecondaryAddress:
          type:
          - string
          - 'null'
          description: Secondary address line (apartment number, floor, etc.)
        City:
          type:
          - string
          - 'null'
          description: City of the employee's residence
        Zip:
          type:
          - string
          - 'null'
          description: Postal code of the employee's residence
        Country:
          type:
          - string
          - 'null'
          description: Country of the employee's residence
        HolidayAgreementNumber:
          type:
          - integer
          - 'null'
          description: The chosen holiday agreement number. Valid numbers are 0, 10, 20 or 30. If null, the employee is a draft employee
          format: int32
        UsesPayslip:
          type: boolean
          description: Indicates whether the employee receives digital payslips
        UsesWorkingTimeAccountOrReserve:
          type: boolean
          description: Indicates whether the employee uses working time account or reserve functionality
        EmployeeCategory:
          type:
          - integer
          - 'null'
          description: 'Employee category<br/>Possible values: 0 - WhiteCollar, 1 - BlueCollar'
          format: int32
        SalaryType:
          type: integer
          description: 'Salary type for the employee<br/>Possible values: 1 - Monthly, 2 - Hourly'
          format: int32
        Type:
          type: integer
          description: 'Employee type. Only regular employees can use shortcuts<br/>Possible values: 0 - Regular, 1 - Limited'
          format: int32
        State:
          type: integer
          description: 'State of the employee. Draft employees are missing information and cannot be used in payroll runs or have shortcuts connected to them<br/>Possible values: 0 - Draft, 1 - Full'
          format: int32
        ContractEndDate:
          type:
          - string
          - 'null'
          description: The end date of the employee's contract, if applicable
          format: date-time
        LastLockedDeviationDate:
          type:
          - string
          - 'null'
          description: Last date when deviations were locked for this employee
          format: date-time
        ModifiedUtc:
          type: string
          description: Timestamp when the employee record was last modified (UTC)
          format: date-time
        HolidayRemainingUnpayed:
          type:
          - number
          - 'null'
          description: Remaining unpaid holiday days in decimal format
          format: double
        HolidayRemainingSaved:
          type:
          - number
          - 'null'
          description: Remaining saved holiday days in decimal format
          format: double
        HolidayRemainingPayed:
          type:
          - number
          - 'null'
          description: Remaining paid holiday days in decimal format
          format: double
        HolidayRemainingAdvance:
          type:
          - number
          - 'null'
          description: Remaining advance holiday days in decimal format
          format: double
        CompensationTimeBalanceInMinutes:
          type:
          - number
          - 'null'
          description: Compensation time balance in minutes
          format: double
        TimeResereveType:
          type:
          - integer
          - 'null'
          description: 'Type of time bank reserve<br/>Possible values: 1 - WorkingTimeReserve, 2 - WorkingTimeAcount'
          format: int32
        TimeResereveInMinutes:
          type:
          - number
          - 'null'
          description: Amount of minutes accumulated in the time bank reserve
          format: double
        UsesVLAFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses VLA (Visma Leave Application)
          format: date-time
        UsesVLA:
          type: boolean
          description: Indicates whether the employee uses VLA (Visma Leave Application)
        UsesCompanyExpenseFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses company expense management
          format: date-time
        EmployeeAgreements:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EmployeeAgreementResponse'
          description: List of agreements associated with the employee
        EmployeeWorkingSchedules:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EmployeeWorkingScheduleResponse'
          description: List of working schedules associated with the employee
      additionalProperties: false
    CreateEmployeeResponse:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the employee
          format: uuid
        FirstName:
          type:
          - string
          - 'null'
          description: Employee's first name
        LastName:
          type:
          - string
          - 'null'
          description: Employee's last name
        IdentificationNumber:
          type:
          - string
          - 'null'
          description: Personal identification number (personnummer) of the employee
        EmployeeNumber:
          type:
          - string
          - 'null'
          description: Employee number assigned by the company
        PhoneMobile:
          type:
          - string
          - 'null'
          description: Employee's mobile phone number
        PhoneWork:
          type:
          - string
          - 'null'
          description: Employee's work phone number
        EmailWork:
          type:
          - string
          - 'null'
          description: Employee's work email address. Can be null
        PrimaryAddress:
          type:
          - string
          - 'null'
          description: Primary street address line of the employee's residence
        SecondaryAddress:
          type:
          - string
          - 'null'
          description: Secondary address line (apartment number, floor, etc.)
        City:
          type:
          - string
          - 'null'
          description: City of the employee's residence
        Zip:
          type:
          - string
          - 'null'
          description: Postal code of the employee's residence
        Country:
          type:
          - string
          - 'null'
          description: Country of the employee's residence
        HolidayAgreementNumber:
          type:
          - integer
          - 'null'
          description: The chosen holiday agreement number. Valid numbers are 0, 10, 20 or 30. If null, the employee is a draft employee
          format: int32
        UsesPayslip:
          type: boolean
          description: Indicates whether the employee receives digital payslips
        UsesWorkingTimeAccountOrReserve:
          type: boolean
          description: Indicates whether the employee uses working time account or reserve functionality
        EmployeeCategory:
          type:
          - integer
          - 'null'
          description: 'Employee category classification<br/>Possible values: 0 - WhiteCollar, 1 - BlueCollar'
          format: int32
        SalaryType:
          type: integer
          description: 'Salary type for the employee<br/>Possible values: 1 - Monthly, 2 - Hourly'
          format: int32
        Type:
          type: integer
          description: 'Employee type. Only regular employees can use shortcuts<br/>Possible values: 0 - Regular, 1 - Limited'
          format: int32
        State:
          type: integer
          description: 'State of the employee. Draft employees are missing information and cannot be used in payroll runs or have shortcuts connected to them<br/>Possible values: 0 - Draft, 1 - Full'
          format: int32
        ContractEndDate:
          type:
          - string
          - 'null'
          description: The end date of the employee's contract, if applicable
          format: date-time
        LastLockedDeviationDate:
          type:
          - string
          - 'null'
          description: Last date when deviations were locked for this employee
          format: date-time
        ModifiedUtc:
          type: string
          description: Timestamp when the employee record was last modified (UTC)
          format: date-time
        CreatedUtc:
          type: string
          description: Timestamp when the employee record was created (UTC)
          format: date-time
        HolidayRemainingUnpayed:
          type:
          - number
          - 'null'
          description: Remaining unpaid holiday days in decimal format
          format: double
        HolidayRemainingSaved:
          type:
          - number
          - 'null'
          description: Remaining saved holiday days in decimal format
          format: double
        HolidayRemainingPayed:
          type:
          - number
          - 'null'
          description: Remaining paid holiday days in decimal format
          format: double
        HolidayRemainingAdvance:
          type:
          - number
          - 'null'
          description: Remaining advance holiday days in decimal format
          format: double
        CompensationTimeBalanceInMinutes:
          type:
          - number
          - 'null'
          description: Compensation time balance in minutes
          format: double
        TimeResereveType:
          type:
          - integer
          - 'null'
          description: 'Type of time bank reserve<br/>Possible values: 1 - WorkingTimeReserve, 2 - WorkingTimeAcount'
          format: int32
        TimeResereveInMinutes:
          type:
          - number
          - 'null'
          description: Amount of minutes accumulated in the time bank reserve
          format: double
        UsesVLAFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses VLA (Visma Leave Application)
          format: date-time
        UsesVLA:
          type: boolean
          description: Indicates whether the employee uses VLA (Visma Leave Application)
        UsesCompanyExpenseFromDate:
          type:
          - string
          - 'null'
          description: Date from which the employee uses company expense management
          format: date-time
        Contract:
          allOf:
          - $ref: '#/components/schemas/CreateEmployeeContractResponse'
          description: Contract details for the created employee
      additionalProperties: false
    CreateEmployeeRequest:
      required:
      - Contract
      - FirstName
      - IdentificationNumber
      - LastName
      type: object
      properties:
        FirstName:
          minLength: 1
          type: string
          description: Employee's first name. Only letters are allowed
        LastName:
          minLength: 1
          type: string
          description: Employee's last name. Only letters are allowed
        EmployeeNumber:
          type:
          - string
          - 'null'
          description: Employee number assigned by the company. If left as null, the next available number will be assigned automatically (e.g. 001, 002)
        IdentificationNumber:
          minLength: 1
          type: string
          description: Personal identification or coordination number (11 or 12 digits)
        EmailWork:
          type:
          - string
          - 'null'
          description: Employee's work email address
        PhoneMobile:
          type:
          - string
          - 'null'
          description: Employee's mobile phone number
        PayslipSendMethod:
          type:
          - integer
          - 'null'
          description: 'Method used to send payslips to the employee. If null it defaults to Pdf<br/>Possible values: 1 - Pdf, 2 - MyPayslip'
          format: int32
        PayslipLanguage:
          type: integer
          description: 'Language used for the employee''s payslip. Defaults to Swedish<

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visma/refs/heads/main/openapi/visma-employees-api-openapi.yml