> ## 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. # Preview a journal template > Preview the journal a template would produce for a pay run, as structured data. ## OpenAPI ````yaml /api-reference/specs/journal.json post /templates/{templateId}/preview openapi: 3.0.1 info: title: Journal Service description: Journal API for FlowPayroll version: v1 servers: - url: https://api.sandbox.flowpayroll.ai/v1/journal security: - X-Auth-Token: [] X-Org-Id: [] tags: - name: Journals description: >- The accounting journals produced from each finalised pay run: list them, retrieve the latest or a specific version for a pay run, review history, rebuild or reissue, and download exports. - name: Journal templates description: >- Define how a pay run becomes an accounting journal. Create, update, clone, preview (as data, CSV, or PDF), import, export, and view the history of templates. - name: Pay element mappings description: Map each pay element to the nominal code it posts to within a template. - name: Control account mappings description: >- Map control accounts (net pay, PAYE, NI, pension, and other liabilities) to nominal codes within a template. - name: Split dimensions description: >- Analysis dimensions such as department or cost centre that split journal lines into tracking categories or account-code segments. - name: Split value mappings description: >- Map each value of a split dimension to its tracking code or account segment. - name: Org journal settings description: Read and update the organisation-level journal defaults. - name: Journal export metadata description: >- Reference data for building templates: export presets, date-format presets, narration and reference tokens, and account-code separators. paths: /templates/{templateId}/preview: post: tags: - Journal templates summary: Preview a journal template description: >- Preview the journal a template would produce for a pay run, as structured data. operationId: PreviewJournalTemplate parameters: - name: templateId in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JournalDetailResponseResponseBody' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' components: schemas: JournalDetailResponseResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: allOf: - $ref: '#/components/schemas/JournalDetailResponseContentResponse' nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false ObjectResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: allOf: - $ref: '#/components/schemas/ObjectContentResponse' nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false JournalDetailResponseContentResponse: type: object properties: data: allOf: - $ref: '#/components/schemas/JournalDetailResponse' nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssue: type: object properties: field: type: string reason: type: string reasonToken: type: string reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ObjectContentResponse: type: object properties: data: nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssueArgument: type: object properties: name: type: string value: nullable: true additionalProperties: false JournalDetailResponse: type: object properties: journal: $ref: '#/components/schemas/JournalResponse' lines: type: array items: $ref: '#/components/schemas/JournalLineResponse' description: The journal's lines; empty when the caller asked to omit them. reconciliation: $ref: '#/components/schemas/ReconciliationResponse' unassignedLineCount: type: integer description: >- Lines posted to the template default because the employee carries no split tag. format: int32 unassignedEmployeeIds: type: array items: type: string description: Employees behind the unassigned lines. nullable: true unmappedValueLineCount: type: integer description: "Lines that ARE tagged but whose split value has no account mapping in\r\nthe template — distinct from `unassignedLineCount` (no tag at all). The\r\nfix differs: add an account mapping vs tag the employee." format: int32 unmappedValueEmployeeIds: type: array items: type: string description: Employees behind the unmapped-value lines. nullable: true unmappedAccountLineCount: type: integer description: "Pay items on a payslip with no account mapping AND no catch-all account,\r\nso they were left out — the usual cause of an off-balance journal." format: int32 unmappedAccountEmployeeIds: type: array items: type: string description: Employees behind the unmapped-account pay items. nullable: true unmappedAccountPayItems: type: array items: type: string description: Names of the pay items left out for lack of an account mapping. nullable: true unmappedAccountAmount: type: number description: Total amount left out for lack of an account mapping. format: double unmappedControlAccountLineCount: type: integer description: "Statutory / employer control accounts (PAYE, NI, student/postgraduate loan,\r\npension, employer NI/pension, levy…) that carried an amount but had no\r\ntemplate mapping, so nothing posted. Credit-only ones unbalance the journal\r\nby their amount; the fix is to add a control-account mapping in the template." format: int32 unmappedControlAccountEmployeeIds: type: array items: type: string description: Employees behind the unmapped control-account amounts. nullable: true unbalancedEmployees: type: array items: $ref: '#/components/schemas/JournalUnbalancedEmployeeResponse' description: "Who is responsible for a journal that doesn't balance. Every employee's own\r\nlines net to zero under double entry, so these are the ones that don't —\r\nwith the amount each is out by. Without this, \"the journal is out by £250\"\r\nmeans reading every line of a 6,000-payslip run by hand." nullable: true unbalancedAmount: type: number description: Amount the journal is out by (debits minus credits). format: double unmappedControlAccountNames: type: array items: type: string description: Names of the control accounts with no template mapping. nullable: true unmappedControlAccountAmount: type: number description: Total amount not posted for lack of a control-account mapping. format: double employees: type: array items: $ref: '#/components/schemas/JournalEmployeeResponse' description: "The employees this response actually references — the warning chips plus\r\nany line still attributed to one person. NOT the pay run's roster: it\r\nlegitimately changes when the line set changes (merging collapses\r\nattribution, employer-level lines belong to no one), so do not assert\r\nagainst its contents." nullable: true summary: allOf: - $ref: '#/components/schemas/JournalSummaryResponse' nullable: true additionalProperties: false ContentMetadataResponse: type: object properties: dateFormat: type: string dateTimeFormat: type: string paginationToken: type: string nullable: true additionalProperties: false JournalResponse: type: object properties: id: type: string description: Journal identifier. organisationId: type: string description: Organisation the journal belongs to. payrollConfigId: type: string description: Payroll configuration (pay schedule) of the pay run. taxYear: type: integer description: Tax year of the pay run. format: int32 taxPeriod: type: integer description: Tax period of the pay run within the tax year. format: int32 payDate: type: string description: Pay date of the pay run. frequency: type: string description: Pay frequency of the payroll configuration. version: type: integer description: >- Version of the journal within its pay run; a reissue creates a new version. format: int32 templateId: type: string description: Journal template the lines were generated from. sumDebit: type: number description: "Stored running total of the journal's debit lines. On a settled journal it\r\nequals the sum of the lines (and `reconciliation.sumDebit`); while a\r\npay run is still calculating, prefer `reconciliation`, which is\r\ncomputed from the very lines in the same response." format: double sumCredit: type: number description: Stored running total of the journal's credit lines. See `sumDebit`. format: double isBalanced: type: boolean description: Whether the journal's debits equal its credits. isFinalised: type: boolean description: Whether the journal is a finalised, immutable snapshot. failureReason: type: string description: Why generation failed, when it did; null otherwise. nullable: true createdBy: type: string description: Who created this journal version. createdDate: type: string description: When this journal version was created (UTC). updatedBy: type: string description: Who last updated the journal. updatedDate: type: string description: When the journal was last updated (UTC). settled: type: boolean description: "Whether this journal has incorporated every payslip change the pay run\r\ncurrently reports. False means the figures are still moving: read again\r\nrather than assert against them. A finalised journal is always settled —\r\nit is an immutable snapshot. On the organisation-wide list the run is not\r\nconsulted, so this reports finalisation only; use the single-journal or\r\npay-run endpoints for the live answer." incorporatedPayslipVersion: type: string description: "The pay-run payslip token this journal has fully incorporated. Compare\r\nsuccessive reads to see progress. Empty on a journal that predates the\r\ntoken, where `settled` falls back to the previous behaviour." additionalProperties: false JournalLineResponse: type: object properties: lineSequence: type: integer format: int32 lineSource: enum: - PayElement - ControlAccount - Apportioned type: string accountCode: type: string description: type: string debit: type: number format: double credit: type: number format: double narration: type: string employeeAttribution: type: string nullable: true dimensions: type: array items: $ref: '#/components/schemas/JournalLineDimensionResponse' groupLabel: type: string nullable: true fellBackToDefault: type: boolean taxCode: type: string nullable: true additionalProperties: false ReconciliationResponse: type: object properties: sumDebit: type: number description: Sum of the returned lines' debits. format: double sumCredit: type: number description: Sum of the returned lines' credits. format: double imbalance: type: number description: SumDebit minus SumCredit; zero on a balanced journal. format: double isBalanced: type: boolean description: True when the imbalance is exactly zero. imbalancePerNominal: type: array items: $ref: '#/components/schemas/NominalImbalanceResponse' description: "Only the nominal codes whose debits and credits do not net off — empty on\r\na balanced journal." additionalProperties: false description: "Totals computed while serving this request from the very lines in the same\r\nresponse — never a stored figure, so they can never disagree with the\r\nlines. Assert against these; on a settled journal they also equal the\r\njournal's stored `sumDebit`/`sumCredit`." JournalUnbalancedEmployeeResponse: type: object properties: employeeId: type: string name: type: string nullable: true payrollId: type: string nullable: true netImbalance: type: number format: double additionalProperties: false JournalEmployeeResponse: type: object properties: employeeId: type: string name: type: string nullable: true payrollId: type: string nullable: true additionalProperties: false description: "Resolved identity for an employee the journal references: the stable\r\nemployee id, the display name, and the payroll reference. Employer-level\r\nlines (e.g. the Employment Allowance pair) carry no employee at all." JournalSummaryResponse: type: object properties: byNominal: type: array items: $ref: '#/components/schemas/JournalNominalSummaryRow' byDepartment: type: array items: $ref: '#/components/schemas/JournalDepartmentSummaryRow' issueLineCount: type: integer format: int32 totalLineCount: type: integer format: int32 additionalProperties: false JournalLineDimensionResponse: type: object properties: name: type: string value: type: string additionalProperties: false NominalImbalanceResponse: type: object properties: accountCode: type: string sumDebit: type: number format: double sumCredit: type: number format: double imbalance: type: number format: double additionalProperties: false JournalNominalSummaryRow: type: object properties: accountCode: type: string description: type: string debit: type: number format: double credit: type: number format: double additionalProperties: false JournalDepartmentSummaryRow: type: object properties: label: type: string debit: type: number format: double credit: type: number format: double additionalProperties: false securitySchemes: X-Auth-Token: type: apiKey description: FlowPayroll JWT (raw token, no Bearer prefix) name: X-Auth-Token in: header X-Org-Id: type: apiKey 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). name: X-Org-Id in: header ````