> ## 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. # Unlock a locked payroll run > Needs permission pay-run:unlock. Reopens a locked, completed payroll run so its payslips can be changed and the run locked again. The run answers at once as Reopened (every payslip) or PartiallyReopened (the listed employees only); the payslips are reopened asynchronously, each keeping the version it had when the run was locked (see the payslip versions endpoints). Every later locked run of the payroll config is unlocked with it, with the same scope and reason, because its payslips were calculated from this run's cumulatives: the answer lists them as `alsoUnlocked`, and they are locked again in period order, this run first (the lock refuses a run while an earlier one is open). A later run already partially reopened for other employees is widened instead of skipped: the employees in scope join its current cycle's unlock (or the cycle goes to Full), and it is listed under `alsoUnlocked` too. The same widening is available on the run itself: unlocking a PartiallyReopened run for more employees, or in full, adds to its open cycle rather than starting a new one. Every guard is checked on every run before anything is reopened. A run in a finalised tax year is never unlocked, and the last period of a tax year is closed once 5 April has passed. The next lock of each run starts its lock cycle n+1 and issues only the reopened payslips. ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml post /payroll/{payrollConfigId}/{year}/{period}/unlock 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: Salary description: >- The employee's effective-dated annual salary history: read it, add or correct a version from a date, and remove one. The Salary API pro-rates this history onto each pay run. - name: Payroll - name: Payroll lines - name: PayrollConfig - name: Pay Elements - name: Calculator - name: Payslip - name: RTI - name: YearEnd - name: Organisation paths: /payroll/{payrollConfigId}/{year}/{period}/unlock: post: tags: - Payroll summary: Unlock a locked payroll run description: >- Needs permission pay-run:unlock. Reopens a locked, completed payroll run so its payslips can be changed and the run locked again. The run answers at once as Reopened (every payslip) or PartiallyReopened (the listed employees only); the payslips are reopened asynchronously, each keeping the version it had when the run was locked (see the payslip versions endpoints). Every later locked run of the payroll config is unlocked with it, with the same scope and reason, because its payslips were calculated from this run's cumulatives: the answer lists them as `alsoUnlocked`, and they are locked again in period order, this run first (the lock refuses a run while an earlier one is open). A later run already partially reopened for other employees is widened instead of skipped: the employees in scope join its current cycle's unlock (or the cycle goes to Full), and it is listed under `alsoUnlocked` too. The same widening is available on the run itself: unlocking a PartiallyReopened run for more employees, or in full, adds to its open cycle rather than starting a new one. Every guard is checked on every run before anything is reopened. A run in a finalised tax year is never unlocked, and the last period of a tax year is closed once 5 April has passed. The next lock of each run starts its lock cycle n+1 and issues only the reopened payslips. operationId: UnlockPayroll parameters: - name: payrollConfigId in: path required: true schema: type: string description: The payroll config id - name: year in: path required: true schema: type: integer format: int32 description: The year in format yyyy example: 2026 - name: period in: path required: true schema: type: integer format: int32 description: The period of the pay run (1, 2, 3... etc) example: 7 - $ref: '#/components/parameters/Request-Id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnlockPayrollRunDto' responses: '202': description: >- The run, and every later locked run of the payroll config, is reopened and their payslips are being reopened content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: $ref: '#/components/schemas/UnlockPayrollRunResultDto' '400': description: >- The request is invalid (unlock_payroll_run_body_required, unlock_payroll_run_invalid_scope, unlock_payroll_run_employee_ids_required, unlock_payroll_run_reason_required) content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '404': description: The payroll config or the payroll run was not found content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '409': description: >- The run, or a later locked run that would be unlocked with it, cannot be unlocked; the message names the run. The token says why: unlock_payroll_run_disabled (not enabled in this environment), unlock_payroll_run_year_to_date_source_off (the organisation is not on the payslip year-to-date source, which a correction is calculated from), unlock_payroll_run_not_locked (neither locked nor partially reopened), unlock_payroll_run_already_reopened (a partially reopened run whose open cycle already covers every employee asked for), unlock_payroll_run_not_completed (a lock is still processing), unlock_payroll_run_tax_year_finalised, unlock_payroll_run_tax_year_closed (the last period of a tax year that has ended). A leaver whose P45 is already issued is reopened like anyone else: the correction reaches HMRC on the next FPS, never as a new P45, and the run's history names them under leaversWithIssuedP45 content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: An error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: parameters: Request-Id: name: Request-Id in: header required: false description: >- Optional. Your id for this request: it is carried into every log line about it, so quote it when you contact support. schema: type: string schemas: UnlockPayrollRunDto: type: object description: The body of `POST /payroll/{payrollConfigId}/{year}/{period}/unlock`. properties: scope: type: string description: >- What to reopen: `Full` (every payslip of the run) or `Employees` (the listed employees' payslips only) employeeIds: type: array items: type: string nullable: true description: >- The employees whose payslips to reopen. Required for the `Employees` scope, ignored otherwise reason: type: string description: >- Why the run is being unlocked. Recorded on the lock cycle and on every payslip version it supersedes. A leaver whose P45 is already issued is reopened like anyone else: the correction reaches HMRC on the next FPS, never as a new P45, and the run's history names them under `leaversWithIssuedP45` ResponseBody: type: object required: - message properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' description: >- A readable message about the outcome and a stable token a client can branch on. content: type: object required: - metadata properties: data: description: >- The resource or list the request asked for; left out when there is none. metadata: type: object required: - dateFormat - dateTimeFormat properties: dateFormat: type: string description: The format of the dates in this response, yyyy-MM-dd. dateTimeFormat: type: string description: >- The format of the timestamps in this response, yyyy-MM-ddTHH:mm:ss.fffZ in UTC. paginationToken: type: string nullable: true description: >- Send this value back as the paginationToken query parameter to get the next page; absent when there are no more pages. description: >- The date formats the response uses and, on a paged list, the token for the next page. description: >- The data the request returns with its metadata; left out on a response that carries no data, such as most errors. validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true description: >- Each field the request was refused for and why; left out when the request was not refused for its fields. UnlockPayrollRunResultDto: type: object description: >- The answer to `POST /payroll/{payrollConfigId}/{year}/{period}/unlock`: the run that was asked for, and every later locked run of the payroll config reopened with it. required: - payrollRun - alsoUnlocked properties: payrollRun: $ref: '#/components/schemas/PayrollRunEntryDto' description: The run that was unlocked, as reopened alsoUnlocked: type: array items: $ref: '#/components/schemas/PayrollRunEntryDto' description: >- The later locked runs of the payroll config reopened with it, latest first. Their payslips were calculated from this run's cumulatives, so they take its changes and are locked again in period order, after it. Empty when it was the latest locked run MessageWithTokenResponse: type: object required: - text - token properties: text: type: string description: The message in English, ready to show to a user. token: type: string description: >- A stable snake_case key for the message, so a client can show its own wording or a translation instead of text. tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: >- Values to fill into the client's own wording for token, such as the request id; absent when the message has none. 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. required: - field - reason - reasonToken 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 items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: >- Values to fill into the client's own wording for reasonToken; absent when the reason has none. PayrollRunEntryDto: type: object required: - organisationId - payrollConfigId - year - period - frequency - paymentDate - periodStartDate - periodEndDate - payPeriodStartDate - payPeriodEndDate - status - lockStatus - totalEmployees - totalSucceeded - totalFailed - createdBy - createdDate - updatedBy - updatedDate - hmrcDetails - totalBalances - payslipContentVersion - lockCycle properties: organisationId: type: string description: The organisation ID example: LOAD_TEST payrollConfigId: type: string description: The payroll config ID example: 01JNR9P81W74HYCN35X1EEFDZE year: type: integer format: int32 description: The year in format yyyy example: 2024 period: type: string description: The period in format mm example: '2' frequency: type: string enum: - Annual - Monthly - FourWeekly - Fortnightly - Weekly - Daily - Quarterly - BiAnnually description: >- The pay frequency, Valid values: 'Annual', 'Monthly', 'FourWeekly', 'Fortnightly', 'Weekly', 'Daily'. example: Monthly paymentDate: type: string format: date description: The payment date in format yyyy-mm-dd example: '2024-05-06' periodStartDate: type: string description: The start date of the tax period in format yyyy-mm-dd example: '2024-05-06' periodEndDate: type: string description: The end date of the tax period in format yyyy-mm-dd example: '2024-06-05' payPeriodStartDate: type: string description: The start date of the pay period in format yyyy-mm-dd example: '2024-05-01' payPeriodEndDate: type: string description: The end date of the pay period in format yyyy-mm-dd example: '2024-05-31' status: type: string enum: - Processing - Completed - Open description: >- The status of the payroll run, Valid values: 'Completed', 'Processing'. example: Completed lockStatus: type: string enum: - Locked - Unlocked - Reopened - PartiallyReopened description: >- The lock status of the payroll run, Valid values: 'Locked', 'Unlocked', 'Reopened', 'PartiallyReopened'. Only 'Locked' freezes the payslips; a reopened run accepts changes to its reopened payslips until it is locked again. example: Locked totalEmployees: type: integer format: int32 description: >- The total number of employees in the payroll run, including employees with no payroll line items. example: 10 totalSucceeded: type: integer format: int32 description: >- The total number of employees in the payroll run that have successfully been processed. example: 10 totalFailed: type: integer format: int32 description: >- The total number of employees in the payroll run that have failed to be processed. example: 0 createdBy: type: string description: The user ID of who created the payroll run example: System createdDate: type: string description: The date and time the payroll run was created example: '2025-03-21T14:17:16.126Z' updatedBy: type: string description: The user ID of who updated the payroll run example: System updatedDate: type: string description: The date and time the payroll run was updated example: '2025-03-21T14:17:19.320Z' completedDate: type: string nullable: true description: The date and time the payroll run was completed example: '2025-03-21T14:17:19.320Z' lockedBy: type: string nullable: true description: The user ID of who locked the payroll run example: System lockedDate: type: string nullable: true description: >- When the pay run was last locked (UTC timestamp); null if it has never been locked. hmrcDetails: $ref: '#/components/schemas/PayrollRunEntryHmrcDetailsDto' description: The HMRC details for the payroll run totalBalances: $ref: '#/components/schemas/PayrollRunBalancesDto' description: The balances for the payroll run payslipContentVersion: type: integer format: int64 description: >- Increments when payslip content changes, so consumers can detect a rebuild. provisionalAllowances: allOf: - $ref: '#/components/schemas/ProvisionalRunAllowancesDto' nullable: true description: >- What this run would claim from the annual Employment Allowance and Apprenticeship Levy allowance pots if it locked now. Returned only while the run is open and the caller supplies runEmployerNi and runPayBill; once the run is locked the settled figures are on totalBalances instead. lockCycle: type: integer format: int32 description: >- How many times the run has been locked, counting the lock in progress or the last one. 1 for a run that has never been unlocked. Each cycle's files, FPS submissions and payslip versions are listed under the run's lock history. example: 1 ValidationIssueArgument: type: object required: - name - value properties: name: type: string description: The name of the value, as a client's wording refers to it. value: description: The value itself, as a string, number or other JSON value. PayrollRunEntryHmrcDetailsDto: type: object required: - fullPaymentSubmissionReportDetails properties: fullPaymentSubmissionReportDetails: $ref: '#/components/schemas/PayrollRunEntryFpsHmrcDetailsDto' description: The details of the full payment submission report PayrollRunBalancesDto: type: object description: >- Payroll run balances containing base values and statutory payments reclaims required: - baseValues - statutoryPaymentsReclaims properties: baseValues: $ref: '#/components/schemas/BaseValuesDto' description: Base values for the payroll run statutoryPaymentsReclaims: type: object additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' description: Dictionary of statutory payments reclaims by type ProvisionalRunAllowancesDto: type: object description: >- Allowance amounts an open pay run would claim if it locked as it currently stands. required: - employmentAllowance - apprenticeshipLevyAllowance properties: employmentAllowance: type: number format: decimal description: Employment Allowance this run would claim example: 1250 apprenticeshipLevyAllowance: type: number format: decimal description: Apprenticeship Levy allowance this run would use example: 1250 PayrollRunEntryFpsHmrcDetailsDto: type: object required: - hmrcFpsReportStatus properties: hmrcFpsSubmissionId: type: string nullable: true description: The id of the FPS HMRC submission hmrcFpsSubmissionDate: type: string nullable: true description: The date and time the FPS HMRC submission was sent hmrcFpsReportStatus: type: string enum: - NotSent - Sending - Sent - Failed - GeneratingPreview - PreviewReady description: The status of the FPS HMRC submission example: NotSent correlationId: type: string nullable: true description: The correlation ID of the FPS HMRC submission example: '1234567890' submissionBody: type: string nullable: true description: The XML of the FPS submission serialized to a string submissionResponse: type: string nullable: true description: The XML of the FPS submission response serialized to a string errors: type: array items: type: string nullable: true description: The errors of the FPS HMRC submission example: - Error 1 - Error 2 submissionDownloadUrl: type: string nullable: true description: A link that downloads the submitted FPS XML, valid for 15 minutes previewDownloadUrl: type: string nullable: true description: A link that downloads the preview XML, valid for 15 minutes lateReason: type: string enum: - NotionalPaymentToExpartByThirdPartyOrOverseasEmployer - NotionalPaymentEmploymentRelatedSecurity - NotionalPaymentOther - PaymentSubjectToClass1NicButP11dP9dForTax - MicroEmployerUsingTemporaryOnOrBeforeRelaxation - >- NoRequirementToMaintainADeductionsWorkingSheetOrImpossibleToReportWorkDoneOnTheDay - ReasonableExcuse - CorrectionToEarlierSubmission description: >- The HMRC late reporting reason the FPS was sent with (or, while a preview is ready, the one the preview was built with). Null when the FPS was reported on time or has not been sent. The values map to HMRC codes A, B, C, D, F, G and H respectively. 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 grossPensionable: type: number format: decimal description: Gross pensionable pay example: 306 grossForCourtOrders: type: number format: decimal description: Gross pay for court orders example: 306 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: >- The member's pension movement for the slice this object covers (period, year to date or employment to date): contributions deducted from pay, including additional voluntary contributions, minus any opt-out refunds paid back. Negative in a period that refunds more than it deducts. Salary-sacrifice contributions are employer money and live in employerPension, never here. Reconciles with the pension summary items: read one source or the other, never both. 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 employerPension: type: number format: decimal description: >- The employer's pension contributions for the slice, including salary-sacrifice amounts (sacrificed pay is the employer's contribution), minus any salary-sacrifice opt-out refunds. 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 additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' description: National Insurance band breakdown statutory: type: object additionalProperties: type: number format: decimal description: Statutory payments breakdown example: SSP: 0 SMP: 0 pensionContributionsByType: type: object additionalProperties: type: number format: decimal description: >- Pension contributions broken down by pension type. Contributions only: opt-out refunds never appear here, so read pensionRefundsByType for those. Net member movement per scheme = contributions minus refunds. 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 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 retain their historical share. Per-employee views are derived from the run-level figure. example: 0 statutoryRecovery: type: object additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' 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. 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 pensionRefundsByType: type: object additionalProperties: type: number format: decimal description: >- The MEMBER contributions paid back through this period, broken down by pension type. Absent unless a refund happened. The refund also appears as a Payable internal_pension_{scheme}_refund summary item and nets forPeriod.pension, so the period scalar can be negative in a refund period. The employer half is reported separately in employerPensionRefundsByType. example: ReliefAtSource: 146.76 employerPensionRefundsByType: type: object additionalProperties: type: number format: decimal description: >- The EMPLOYER contributions reversed by an opt-out refund, broken down by pension type. Absent unless a refund happened. Employer money never passes through the member's net pay (the scheme repays the employer directly), but it is netted off employerPension for the period, and therefore off the monthly balance, the organisation year-to-date figures and the journal cost slices built from it. This field is the disclosure of what was reversed, so read it to explain a balance, never to subtract again. example: ReliefAtSource: 110.07 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 NiCalculationResultDto: type: object properties: employeeNi: type: number format: decimal description: Employee National Insurance under this NI category letter. employerNi: type: number format: decimal description: Employer National Insurance under this NI category letter. totalNi: type: number format: decimal description: Employee and employer National Insurance added together. grossForEmployeeNi: type: number format: decimal description: >- Earnings that employee National Insurance was worked out on under this letter. grossForEmployerNi: type: number format: decimal description: >- Earnings that employer National Insurance was worked out on under this letter. bandResults: type: object additionalProperties: $ref: '#/components/schemas/NiBandResultDto' description: >- The same figures split by National Insurance band, keyed by band name. 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 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). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.