openapi: 3.0.1
info:
  version: 1.0.1
  title: Leapsome absences payroll API
  contact:
    name: Support
    url: https://leapsome.zendesk.com
  description: The Content API enables you to export some raw data from Leapsome for usage within your own systems and beyond what the Leapsome application offers natively. Usage is restricted to a maximum of 20 requests per second when making requests in parallel. If you exceed this limit, you will receive a 429 status code.
servers:
- url: https://api.leapsome.com/v1
tags:
- name: payroll
paths:
  /payroll-cycles:
    get:
      summary: List payroll cycles
      description: Get a paginated list of payroll cycles with optional filtering by name or status. Returns payroll cycle details including dates, status, and compensation configuration. Requires permission to manage payroll policies.
      operationId: listPayrollCycles
      security:
      - bearerAuth: []
      tags:
      - payroll
      parameters:
      - name: name
        in: query
        required: false
        description: Filter by payroll cycle name (partial match, case-insensitive)
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter by payroll cycle status
        schema:
          type: string
          enum:
          - draft
          - active
          - completed
          - archived
      - name: offset
        in: query
        required: false
        description: Number of results to skip
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: A list of payroll cycles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollCycleList'
        '401':
          description: Authorization failed. Token is missing or invalid.
        '403':
          description: Insufficient permissions. Permission to manage payroll policies is required.
  /payroll-cycles/{payrollCycleId}/participants:
    get:
      summary: List payroll cycle participants
      description: Get participants for a specific payroll cycle with optional filtering by username (email) or employee ID. Requires permission to manage payroll policies.
      operationId: listPayrollCycleParticipants
      security:
      - bearerAuth: []
      tags:
      - payroll
      parameters:
      - name: payrollCycleId
        in: path
        required: true
        description: ID of the payroll cycle
        schema:
          type: string
          pattern: ^[0-9a-f]{24}$
      - name: username
        in: query
        required: false
        description: Filter by employee email address
        schema:
          type: string
          format: email
      - name: employeeId
        in: query
        required: false
        description: Filter by Leapsome employee ID
        schema:
          type: string
          pattern: ^[0-9a-f]{24}$
      - name: offset
        in: query
        required: false
        description: Number of results to skip
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: A list of payroll cycle participants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollCycleParticipantList'
        '401':
          description: Authorization failed. Token is missing or invalid.
        '403':
          description: Insufficient permissions. Permission to manage payroll policies is required.
        '404':
          description: Payroll cycle not found.
components:
  schemas:
    PayrollCycleList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PayrollCycle'
        meta:
          type: object
          properties:
            page:
              type: integer
              description: Current page number
            pageSize:
              type: integer
              description: Number of items per page
            totalCount:
              type: integer
              description: Total number of payroll cycles
    PayrollCycleParticipantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PayrollCycleParticipant'
        meta:
          type: object
          properties:
            page:
              type: integer
              description: Current page number
            pageSize:
              type: integer
              description: Number of items per page
            totalCount:
              type: integer
              description: Total number of participants
    PayrollCycle:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-f]{24}$
          example: 58d55e3ffdc2eb20547edd0a
          description: Payroll cycle ID
        name:
          type: string
          example: Q1 2024 Payroll
          description: Name of the payroll cycle
        status:
          type: string
          enum:
          - open
          - pendingApproval
          - approved
          - overdue
          - future
          - reopened
          example: open
          description: Current status of the payroll cycle
        startAt:
          type: string
          format: date-time
          description: Start date of the payroll period
        endAt:
          type: string
          format: date-time
          description: End date of the payroll period
        customPeriodStartAt:
          type: string
          format: date-time
          description: Start date of the custom period
        customPeriodEndAt:
          type: string
          format: date-time
          description: End date of the custom period
        reviewStartAt:
          type: string
          format: date-time
          description: Start date of the review period
        approvalStartAt:
          type: string
          format: date-time
          description: Start date of the approval period
        approvedAt:
          type: string
          format: date-time
          description: Date when the payroll cycle was approved
        approvedBy:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: User ID of the user who approved the payroll cycle
        prorateType:
          type: string
          enum:
          - weekly
          - biWeekly
          - semiMonthly
          - thirtyDays
          - actualNumberOfMonthDays
          example: weekly
          description: Type of prorate used for the payroll cycle
        compensations:
          type: object
          properties:
            salaryTypeCustomName:
              type: string
              description: Custom name for the salary type
            baseSalaryCustomName:
              type: string
              description: Custom name for the base salary
            salaryPerHourCustomName:
              type: string
              description: Custom name for the salary per hour
            compensableTimeCustomName:
              type: string
              description: Custom name for the compensable time
            hoursWorkedCustomName:
              type: string
              description: Custom name for the hours worked
            paidAbsencesCustomName:
              type: string
              description: Custom name for the paid absences
        createdAt:
          type: string
          format: date-time
          description: When the payroll cycle was created
        updatedAt:
          type: string
          format: date-time
          description: When the payroll cycle was last updated
    PayrollCycleParticipant:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-f]{24}$
          example: 58d55e3ffdc2eb20547edd0a
          description: Payroll cycle participant ID
        name:
          type: string
          example: John Doe
          description: Name of the participant
        email:
          type: string
          format: email
          example: jane.doe@example.com
          description: Email address of the participant
        compensations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the compensation
              amount:
                type: number
                description: Amount of the compensation
              amountType:
                type: string
                enum:
                - fixed
                - variable
                description: Type of the compensation
              recurrence:
                type: string
                enum:
                - monthly
                - every3Months
                - every6Months
                - every12Months
                description: Recurrence of the compensation
              comment:
                type: string
                description: Comment for the compensation
              effectiveAt:
                type: string
                format: date-time
                description: Effective date of the compensation
              validUntil:
                type: string
                format: date-time
                description: Valid until date of the compensation
        salaryInfoPeriods:
          type: array
          items:
            type: object
            properties:
              currency:
                type: string
              salary:
                type: number
                description: Salary for the period
              salaryRemunerationPeriod:
                type: string
                enum:
                - year
                - month
                - hour
                description: Remuneration period of the salary
              compensationType:
                type: string
                enum:
                - fixed
                - hourly
                description: Type of the compensation
              baseSalary:
                type: number
                description: Base salary for the period
        isActiveParticipant:
          type: boolean
          description: Whether the participant is active in the payroll cycle
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT