> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplifi.work/llms.txt
> Use this file to discover all available pages before exploring further.

# List all pay periods

> Returns a list of all the pay periods/calendars in your organisation.



## OpenAPI

````yaml /simplifi_openapi.json get /payperiods
openapi: 3.0.3
info:
  title: Simplifi API
  version: 1.0.0
  description: Workforce management API
  termsOfService: >-
    https://apps.staffsync.co.nz/static/StaffSyncUserTermsOfService.pdf?openexternal=true
  contact:
    name: Simplifi
    email: support@simplifi.work
    url: https://simplifi.work
servers:
  - url: https://{base_url}/api/v1
    description: Simplifi API Server
    variables:
      base_url:
        description: Your Simplifi instance base URL
        default: example.com
security:
  - BearerAuth: []
externalDocs:
  url: https://docs.simplifi.work/authentication
  description: The Simplifi API Documentation
paths:
  /payperiods:
    get:
      tags:
        - Pay Periods
      summary: List all pay periods
      description: Returns a list of all the pay periods/calendars in your organisation.
      operationId: listPayPeriods
      responses:
        '200':
          description: A list of pay periods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayPeriod'
              example:
                - id: '2106_898371'
                  calendar: Weekly
                  closed: null
                  finishDate: '2026-04-22'
                  hours: 0
                  numberEmployees: 0
                  numberTimesheets: 0
                  payRollCompanyId: ''
                  payRollProvider: iPayroll
                  startDate: '2026-04-16'
                - id: '2106_898372'
                  calendar: Weekly
                  closed: null
                  finishDate: '2026-04-15'
                  hours: 0
                  numberEmployees: 0
                  numberTimesheets: 0
                  payRollCompanyId: ''
                  payRollProvider: iPayroll
                  startDate: '2026-04-09'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    PayPeriod:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the pay period
          example: '2106_898371'
        calendar:
          type: string
          description: The name of the pay calendar this period belongs to
          example: Weekly
        closed:
          type: string
          nullable: true
          description: >-
            The date the pay period was closed, in YYYY-MM-DD format. Null if
            not yet closed.
          example: null
        finishDate:
          type: string
          format: date
          description: The end date of the pay period in YYYY-MM-DD format
          example: '2026-04-22'
        hours:
          type: number
          description: Total hours worked in this pay period
          example: 0
        numberEmployees:
          type: integer
          description: The number of employees with timesheets in this pay period
          example: 0
        numberTimesheets:
          type: integer
          description: The total number of timesheets in this pay period
          example: 0
        payRollCompanyId:
          type: string
          description: The payroll company identifier. Empty string if not assigned.
          example: ''
        payRollProvider:
          type: string
          description: The name of the payroll provider for this pay period
          example: iPayroll
        startDate:
          type: string
          format: date
          description: The start date of the pay period in YYYY-MM-DD format
          example: '2026-04-16'
  responses:
    BadRequest:
      description: Bad Request - malformed request syntax or invalid parameters
    Unauthorized:
      description: Unauthorized - missing or invalid token
    Forbidden:
      description: Forbidden - valid token but insufficient permissions
    NotFound:
      description: Not Found - the requested resource does not exist
    Conflict:
      description: Conflict - the request conflicts with the current state of the resource
    UnprocessableEntity:
      description: >-
        Unprocessable Entity - the request was well-formed but contains semantic
        errors
    TooManyRequests:
      description: Too Many Requests - rate limit exceeded
    InternalServerError:
      description: Internal Server Error
    BadGateway:
      description: Bad Gateway - upstream service failed
    ServiceUnavailable:
      description: Service Unavailable
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained from /oauth/token. Pass as Authorization: Bearer
        {token}

````