> ## 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 year-to-date running balances by tax year > Retrieves the year-to-date running balances for the current organisation for a specific tax year ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /organisation/balances/running/{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/running/{taxYear}: get: tags: - Organisation summary: Get year-to-date running balances by tax year description: >- Retrieves the year-to-date running balances for the current organisation for a specific tax year operationId: getRunningBalancesByTaxYear parameters: - name: taxYear in: path required: true schema: type: integer minimum: 1800 maximum: 3000 description: The tax year to retrieve running balances for responses: '200': description: Successfully retrieved running balances content: application/json: schema: allOf: - $ref: '#/components/schemas/ResponseBody' - type: object properties: data: $ref: '#/components/schemas/YearToDateBalancesDto' '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 YearToDateBalancesDto: type: object allOf: - $ref: '#/components/schemas/UpdatableYearToDateBalancesDto' - type: object properties: organisationId: type: string description: Organisation ID example: org_123 createdBy: type: string description: User who created the record example: user_123 updatedBy: type: string description: User who last updated the record example: user_456 createdDate: type: string format: date-time description: Creation date example: '2024-01-01T00:00:00Z' updatedDate: type: string format: date-time description: Last update date example: '2024-01-02T00:00:00Z' required: - organisationId - createdBy - updatedBy - createdDate - updatedDate 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' UpdatableYearToDateBalancesDto: type: object properties: baseValues: $ref: '#/components/schemas/BaseValuesDto' apprenticeshipLevyAllowanceYtd: $ref: '#/components/schemas/AmountUsageDto' apprenticeshipLevyYtd: type: number format: decimal description: Apprenticeship levy owed YTD example: 100 employmentAllowanceYtd: $ref: '#/components/schemas/AmountUsageDto' cisDeductions: $ref: '#/components/schemas/AmountUsageDto' statutoryPaymentsReclaims: type: object additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimBalanceDto' description: >- Dictionary where keys should be one of the StatutoryTypeEnum values (StatutorySickPay, StatutoryMaternityPay, StatutoryPaternityPay, StatutoryAdoptionPay, SharedParentalPay, StatutoryParentalBereavementPay, StatutorySharedParentalPay, StatutoryNeoNatalCarePay) required: - baseValues ValidationIssueArgument: type: object properties: name: type: string value: type: string BaseValuesDto: type: object properties: gross: type: number format: decimal description: Gross pay example: 306 grossTaxable: type: number format: decimal description: Gross taxable pay example: 306 grossNi: type: number format: decimal description: Gross pay for National Insurance purposes example: 306 grossForEmployerNi: type: number format: decimal description: Gross pay for employer National Insurance purposes example: 306 grossForEmployerClass1ANi: type: number format: decimal description: Gross pay for employer Class 1A National Insurance purposes example: 306 nullable: true grossPensionable: type: number format: decimal description: Gross pensionable pay example: 306 grossForCourtOrders: type: number format: decimal description: Gross pay for court orders example: 306 nullable: true tax: type: number format: decimal description: Tax amount example: 45.2 ni: type: number format: decimal description: Employee National Insurance contribution example: 25.3 pension: type: number format: decimal description: Pension contribution example: 0 employerNi: type: number format: decimal description: Employer National Insurance contribution example: 35.4 employerClass1ANI: type: number format: decimal description: Employer Class 1A National Insurance contribution example: 35.4 nullable: true employerPension: type: number format: decimal description: Employer pension contribution example: 0 studentLoan: type: number format: decimal description: Student loan repayment example: 0 postgraduateLoan: type: number format: decimal description: Postgraduate loan repayment example: 0 net: type: number format: decimal description: Net pay after deductions including net deductions example: 235.5 netDeductions: type: number format: decimal description: Net deductions applied to the net pay example: 0 totalPayable: type: number format: decimal description: Total payable example: 235.5 totalEmployerCost: type: number format: decimal description: Total employer cost example: 306 niBand: type: object nullable: true description: National Insurance band breakdown additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' statutory: type: object nullable: true description: Statutory payments breakdown additionalProperties: type: number format: decimal example: SSP: 0 SMP: 0 pensionContributionsByType: type: object nullable: true description: Pension contributions broken down by pension type additionalProperties: type: number format: decimal example: NetPayArrangement: 0 ReliefAtSource: 0 SalarySacrifice: 0 qualifyingEarningsForPension: type: number format: decimal description: Qualifying earnings for pension calculation example: 0 apprenticeshipLevy: type: number format: decimal description: >- Per-payslip gross apprenticeship levy attributable to this period. Equal to 0.5 percent of grossForEmployerNi when the organisation pays AL, otherwise 0. The org-level £15,000 annual allowance is applied at the EPS level, not deducted per payslip — so summing this across a pay run gives the gross levy used for reconciliation against the organisation's monthly AL balance. example: 1.53 employmentAllowance: type: number format: decimal description: >- Employment Allowance used by this pay run — an employer-level figure, populated on the pay run's totalBalances when the run completes. Not stamped on individual payslips: payslip forPeriod/yearToDate values are always 0 for payslips generated after per-payslip apportionment was removed; payslips written while it existed (NeoPayroll 1.4.x) retain their historical share. Per-employee views (journal Employment Allowance lines) are derived from the run-level figure. example: 0 apprenticeshipLevyAllowance: type: number format: decimal description: >- Apprenticeship Levy allowance (annual £15,000 pot, accrued monthly) used by this pay run — an employer-level figure, populated on the pay run's totalBalances when the run completes. Not stamped on individual payslips: payslip forPeriod/yearToDate values are always 0 for payslips generated after per-payslip apportionment was removed; payslips written while it existed (NeoPayroll 1.4.x) retain their historical share. Per-employee views are derived from the run-level figure. example: 0 statutoryRecovery: type: object nullable: true description: >- Per-statutory-type recovery this payslip contributes to the EPS. Keys are the StatutoryTypeEnum string values (StatutoryMaternityPay, StatutoryPaternityPay, SharedParentalPay, StatutoryAdoptionPay, StatutoryParentalBereavementPay, StatutoryNeonatalCarePay). Statutory Sick Pay is never recoverable per HMRC DANSP37000 and is omitted from this map. additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' example: StatutoryMaternityPay: reclaimed: 100 nicCompensationRecovered: 8.5 isEmpty: type: boolean nullable: true description: >- Whether every value in this record is zero, as judged by the producer. A pay run's totalBalances is written asynchronously after the run completes and reads back as an all-zero record until then, so a consumer cannot tell "not written yet" from "genuinely nil" by inspecting the figures. Null means this producer did not supply the flag — treat it as unknown, never as false. example: false AmountUsageDto: type: object properties: amountLeft: type: number format: decimal description: Amount left example: 100 amountUsed: type: number format: decimal description: Amount used example: 100 StatutoryPaymentsReclaimBalanceDto: 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 NiCalculationResultDto: type: object required: - employeeNi - employerNi - totalNi - grossForEmployeeNi - grossForEmployerNi properties: employeeNi: type: number format: decimal employerNi: type: number format: decimal totalNi: type: number format: decimal grossForEmployeeNi: type: number format: decimal grossForEmployerNi: type: number format: decimal bandResults: type: object nullable: true additionalProperties: $ref: '#/components/schemas/NiBandResultDto' example: employeeNi: 290.1 employerNi: 310.25 totalNi: 600.35 grossForEmployeeNi: 3500 grossForEmployerNi: 3500 bandResults: PT-UEL: grossInBand: 2000 employeeNiForBand: 180 employerNiForBand: 220 UEL+: grossInBand: 500 employeeNiForBand: 110.1 employerNiForBand: 90.25 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 NiBandResultDto: type: object properties: grossInBand: type: number format: decimal description: Gross pay in this NI band example: 12570 employeeNiForBand: type: number format: decimal description: Employee NI contribution for this band example: 0 employerNiForBand: type: number format: decimal description: Employer NI contribution for this band example: 0 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). ````