> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # List employees with pagination ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /employees openapi: 3.0.3 info: title: FlowPayroll API description: >- API for payroll management, including payroll upload, lock, HMRC submission, employee management version: 0.1.0 servers: - url: https://api.sandbox.flowpayroll.ai/v1 security: - XAuthToken: [] XOrgId: [] tags: - name: Employees description: >- Create, retrieve, update, and delete employee records, and look them up by NI number or payroll ID. - name: Starters & leavers description: Set and clear starter and leaver details, individually or in bulk. - name: Tax codes description: >- Manage employee tax codes and query the effective tax code and NI category on a given date. - name: NI & identifiers description: Manage NI categories, National Insurance numbers, and payroll IDs. - name: Student loans description: Start and end student and postgraduate loans. - name: Payroll setup description: Assign an employee's payroll config and set opening balances. - name: Payroll - name: Payroll lines - name: PayrollConfig - name: Pay Elements - name: Calculator - name: Payslip - name: RTI - name: YearEnd - name: Organisation paths: /employees: get: tags: - Employees summary: List employees with pagination operationId: ListEmployees parameters: - name: pageSize in: query required: false schema: type: integer minimum: 1 maximum: 100 description: The maximum number of employees to return. - name: paginationToken in: query required: false schema: type: string description: The pagination token for the next page. responses: '200': description: Employees listed successfully content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: type: array items: $ref: '#/components/schemas/EmployeeListItemDto' metadata: type: object properties: paginationToken: type: string nullable: true '500': description: An error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: ResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: type: object properties: data: type: object nullable: true metadata: type: object nullable: true properties: dateFormat: type: string default: yyyy-MM-dd dateTimeFormat: type: string default: yyyy-MM-ddTHH:mm:ss.fffZ paginationToken: type: string nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' messageToken: type: string EmployeeListItemDto: type: object required: - id - payrollConfigId - name - email properties: id: type: string example: emp_12345 payrollConfigId: type: string description: >- ID of the payroll config the employee belongs to. Useful for grouping bulk actions per config without an extra fetch per row. example: config_main_uk payrollId: type: string nullable: true example: payroll_2023_001 employeeCode: type: string nullable: true description: Employee code. An optional identifier for the employee. example: EMP001 nationalInsuranceNumber: type: string example: QQ123456C nullable: true name: $ref: '#/components/schemas/EmployeeNameDto' email: type: string format: email example: john.smith@company.com department: type: string nullable: true example: Engineering jobTitle: type: string nullable: true example: Software Engineer leaverDetails: $ref: '#/components/schemas/EmployeeLeaverDetailsDto' MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' ValidationIssue: type: object description: > Field validation item. `reasonToken` is a stable snake_case key for i18n or custom client messages; `reason` is the default English text from the API. properties: field: type: string description: Dot-path of the field (e.g. name.firstName, address.line1). reason: type: string description: Default human-readable message. reasonToken: type: string description: Machine-readable error identifier (snake_case). reasonTokenArguments: type: array nullable: true items: $ref: '#/components/schemas/ValidationIssueArgument' EmployeeNameDto: type: object required: - firstName - lastName properties: firstName: type: string example: John middleName: type: string nullable: true example: Edward lastName: type: string example: Smith title: type: string nullable: true example: Mr EmployeeLeaverDetailsDto: type: object properties: leavingDate: type: string description: The date the employee left the company. example: '2024-12-31' reason: type: string nullable: true description: The reason the employee left the company. example: Retirement issuedBy: type: string nullable: true description: The entity that issued the leaver certificate. example: Employer reportedToHmrc: type: boolean description: >- Whether the leaving date has been sent to HMRC on an FPS. Set only on a real submission, never on a preview. example: false default: false finalisedOnPayslip: type: boolean description: >- Whether the leaving date is carried by a finalised payslip on a locked pay run. Until this is true the employee stays on the payroll-config roster, so a cessation recorded after its own pay run closed is still picked up and reported on the next one. example: false default: false ValidationIssueArgument: type: object properties: name: type: string value: type: string securitySchemes: XAuthToken: type: apiKey in: header name: X-Auth-Token description: Access token obtained from OAuth2 client credentials flow XOrgId: type: apiKey in: header name: X-Org-Id description: >- Organisation to scope the request to. Required when the principal can access more than one organisation; optional for single-organisation principals (the authorizer resolves it automatically). ````