> ## 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. # Get PAYE liability summary by tax year > Retrieves the PAYE liability summary for the current organisation for a specific tax year, including monthly or quarterly breakdowns based on the organisation's HMRC settings ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /organisation/balances/paye-liability/{taxYear} 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: /organisation/balances/paye-liability/{taxYear}: get: tags: - Organisation summary: Get PAYE liability summary by tax year description: >- Retrieves the PAYE liability summary for the current organisation for a specific tax year, including monthly or quarterly breakdowns based on the organisation's HMRC settings operationId: getPayeLiabilitySummary parameters: - name: taxYear in: path required: true schema: type: integer minimum: 1800 maximum: 3000 description: The tax year to retrieve PAYE liability summary for responses: '200': description: Successfully retrieved PAYE liability summary content: application/json: schema: allOf: - $ref: '#/components/schemas/ResponseBody' - type: object properties: data: type: array items: $ref: '#/components/schemas/PayeLiabilitySummaryDto' description: >- List of PAYE liability summaries (12 for monthly, 4 for quarterly) '400': description: Invalid tax year content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: Internal server error 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 PayeLiabilitySummaryDto: type: object description: Simplified PAYE liability summary for a given period (month or quarter) required: - taxYear - period - dueDate - payFrequency - liability - credits - due - paid - remaining - payments properties: taxYear: type: integer description: The tax year example: 2024 period: type: integer description: The period number (1-12 for monthly, 1-4 for quarterly) example: 5 dueDate: type: string format: date description: The due date for the period (22nd of next tax month or quarter) example: '2024-06-22' payFrequency: type: string description: The frequency of PAYE payments for this period enum: - Monthly - Quarterly example: Monthly liability: $ref: '#/components/schemas/LiabilityBreakdownDto' description: Breakdown of all liability components credits: $ref: '#/components/schemas/CreditsBreakdownDto' description: Breakdown of all credits that reduce the liability due: type: number format: decimal description: Total amount due (Liability - Credits) example: 2300 paid: type: number format: decimal description: Total amount paid for this period example: 1500 remaining: type: number format: decimal description: Remaining amount to be paid (Due - Paid) example: 800 payments: type: array items: $ref: '#/components/schemas/PayePaymentDto' description: List of payments made for this period 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' LiabilityBreakdownDto: type: object description: Breakdown of all liability components required: - total - apprenticeshipLevy - tax - studentLoan - postgraduateLoan - employeeNi - employerNi properties: total: type: number format: decimal description: Total liability amount before credits example: 2500 apprenticeshipLevy: type: number format: decimal description: Apprenticeship levy amount for the period example: 100 tax: type: number format: decimal description: Tax amount for the period example: 1200 studentLoan: type: number format: decimal description: Student loan repayment amount for the period example: 150 postgraduateLoan: type: number format: decimal description: Postgraduate loan repayment amount for the period example: 50 employeeNi: type: number format: decimal description: Employee National Insurance contribution for the period example: 400 employerNi: type: number format: decimal description: Employer National Insurance contribution for the period example: 500 class1ANi: type: number format: decimal description: Class 1A National Insurance contribution for the period example: 50 CreditsBreakdownDto: type: object description: Breakdown of all credits that reduce the liability required: - total - statutoryPaymentsReclaims properties: total: type: number format: decimal description: Total credits amount example: 200 statutoryPaymentsReclaims: type: object additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' description: Breakdown of statutory payments reclaims by type example: SMP: reclaimed: 150 nicCompensationRecovered: 50 SSP: reclaimed: 0 nicCompensationRecovered: 0 employmentAllowance: type: number format: decimal description: Employment allowance for the period example: 100 apprenticeshipLevyAllowance: type: number format: decimal description: Apprenticeship levy allowance for the period example: 100 PayePaymentDto: type: object description: Response containing the recorded PAYE payment details allOf: - $ref: '#/components/schemas/UpdatablePayePaymentDto' - type: object required: - paymentId - organisationId - dueDate - isOnTime - period - taxYear - createdDate - createdBy - updatedDate - updatedBy properties: paymentId: type: string description: The unique identifier for the payment example: PAY_2024_001 organisationId: type: string description: The organisation ID example: org_123 dueDate: type: string format: date description: The due date for this payment (22nd of next tax month) example: '2024-05-22' isOnTime: type: boolean description: Whether the payment was made on time example: true period: type: integer description: The period of the payment (1-12 for monthly, 1-4 for quarterly) example: 5 taxYear: type: integer description: The tax year this payment relates to example: 2024 createdDate: type: string format: date-time description: The created date example: '2024-05-22T10:00:00Z' createdBy: type: string description: The created by example: user_123 updatedDate: type: string format: date-time description: The updated date example: '2024-05-22T10:00:00Z' updatedBy: type: string description: The updated by example: user_123 ValidationIssueArgument: type: object properties: name: type: string value: type: string StatutoryPaymentsReclaimDto: type: object properties: reclaimed: type: number format: decimal description: Amount reclaimed this tax year example: 100 nicCompensationRecovered: type: number format: decimal description: National Insurance contribution compensation recovered this tax year example: 50 required: - reclaimed - nicCompensationRecovered UpdatablePayePaymentDto: type: object description: Request body for recording a PAYE payment required: - paymentReference - amountPaid - paymentDate properties: paymentReference: type: string description: The payment reference used example: PAYE_2024_001 amountPaid: type: number format: decimal description: The amount paid to HMRC example: 1500 paymentDate: type: string format: date description: The date the payment was made example: '2024-05-22' notes: type: string nullable: true description: Notes about the payment (e.g., how it was made, who made it) example: BACS payment via online banking 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). ````