Skip to main content
POST
/
payroll
/
{payrollConfigId}
/
{year}
/
{period}
{
  "organisationId": "LOAD_TEST",
  "payrollConfigId": "01JNR9P81W74HYCN35X1EEFDZE",
  "paymentDate": "2024-05-06",
  "year": 2024,
  "period": "2",
  "frequency": "Monthly",
  "periodStartDate": "2024-05-06",
  "periodEndDate": "2024-06-05",
  "payPeriodStartDate": "2024-05-01",
  "payPeriodEndDate": "2024-05-31",
  "status": "Completed",
  "lockStatus": "Locked",
  "totalEmployees": 10,
  "totalSucceeded": 10,
  "totalFailed": 0,
  "createdBy": "System",
  "createdDate": "2025-03-21T14:17:16.126Z",
  "updatedBy": "System",
  "updatedDate": "2025-03-21T14:17:19.320Z",
  "completedDate": "2025-03-21T14:17:19.320Z",
  "lockedBy": "System",
  "lockedDate": "<string>",
  "hmrcDetails": {
    "fullPaymentSubmissionReportDetails": {
      "hmrcFpsSubmissionId": null,
      "hmrcFpsSubmissionDate": null,
      "hmrcFpsReportStatus": "NotSent",
      "correlationId": "1234567890",
      "errors": [
        "Error 1",
        "Error 2"
      ],
      "submissionBody": "<string>",
      "submissionResponse": "<string>",
      "previewS3Key": null,
      "submissionDownloadUrl": null,
      "previewDownloadUrl": null
    }
  },
  "totalBalances": {
    "baseValues": {
      "gross": 306,
      "grossTaxable": 306,
      "grossNi": 306,
      "grossForEmployerNi": 306,
      "grossForEmployerClass1ANi": 306,
      "grossPensionable": 306,
      "grossForCourtOrders": 306,
      "tax": 45.2,
      "ni": 25.3,
      "pension": 0,
      "employerNi": 35.4,
      "employerClass1ANi": 35.4,
      "employerPension": 0,
      "studentLoan": 0,
      "postgraduateLoan": 0,
      "net": 235.5,
      "netDeductions": 0,
      "totalPayable": 235.5,
      "totalEmployerCost": 306,
      "niBand": {},
      "statutory": {
        "SSP": 0,
        "SMP": 0
      },
      "pensionContributionsByType": {
        "NetPayArrangement": 0,
        "ReliefAtSource": 0,
        "SalarySacrifice": 0
      }
    },
    "statutoryPaymentsReclaims": {
      "SSP": {
        "amount": 100,
        "type": "StatutorySickPay"
      },
      "SMP": {
        "amount": 150,
        "type": "StatutoryMaternityPay"
      }
    }
  }
}

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.

Authorizations

​
X-Auth-Token
string
header
required

Access token obtained from OAuth2 client credentials flow

Path Parameters

​
payrollConfigId
string
required

The ID of the payroll configuration to use.

​
year
integer
required

The payroll year (e.g., 2024).

​
period
integer
required

The payroll period (e.g., 1 for January, 12 for December, or period number for other frequencies).

Query Parameters

​
paymentDateOverride
string<date>

Optional override for the payment date (format: yyyy-MM-dd).

Response

Payroll run created successfully

​
organisationId
string

The organisation ID

Example:

"LOAD_TEST"

​
payrollConfigId
string

The payroll config ID

Example:

"01JNR9P81W74HYCN35X1EEFDZE"

​
paymentDate
string<date>

The payment date in format yyyy-mm-dd

Example:

"2024-05-06"

​
year
integer

The year in format yyyy

Example:

2024

​
period
string

The period in format mm

Example:

"2"

​
frequency
enum<string>

The pay frequency, Valid values: 'Annual', 'Monthly', 'FourWeekly', 'Fortnightly', 'Weekly', 'Daily'.

Available options:
Annual,
Monthly,
FourWeekly,
Fortnightly,
Weekly,
Daily
Example:

"Monthly"

​
periodStartDate
string

The start date of the tax period in format yyyy-mm-dd

Example:

"2024-05-06"

​
periodEndDate
string

The end date of the tax period in format yyyy-mm-dd

Example:

"2024-06-05"

​
payPeriodStartDate
string

The start date of the pay period in format yyyy-mm-dd

Example:

"2024-05-01"

​
payPeriodEndDate
string

The end date of the pay period in format yyyy-mm-dd

Example:

"2024-05-31"

​
status
enum<string>

The status of the payroll run, Valid values: 'Completed', 'Processing'.

Available options:
Completed,
Processing,
Open
Example:

"Completed"

​
lockStatus
enum<string>

The status of the payroll run, Valid values: "Locked", "Unlocked".

Available options:
Locked,
Unlocked
Example:

"Locked"

​
totalEmployees
integer

The total number of employees in the payroll run, including employees with no payroll line items.

Example:

10

​
totalSucceeded
integer

The total number of employees in the payroll run that have successfully been processed.

Example:

10

​
totalFailed
integer

The total number of employees in the payroll run that have failed to be processed.

Example:

0

​
createdBy
string

The user ID of who created the payroll run

Example:

"System"

​
createdDate
string

The date and time the payroll run was created

Example:

"2025-03-21T14:17:16.126Z"

​
updatedBy
string

The user ID of who updated the payroll run

Example:

"System"

​
updatedDate
string

The date and time the payroll run was updated

Example:

"2025-03-21T14:17:19.320Z"

​
completedDate
string | null

The date and time the payroll run was completed

Example:

"2025-03-21T14:17:19.320Z"

​
lockedBy
string | null

The user ID of who locked the payroll run

Example:

"System"

​
lockedDate
string | null
​
hmrcDetails
object

The HMRC details for the payroll run

​
totalBalances
object

The balances for the payroll run