Payroll
Create the next payroll run for a given payroll configuration
POST
/
payroll
/
{payrollConfigId}
/
next
Create the next payroll run for a given payroll configuration
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next"
headers = {
"X-Auth-Token": "<api-key>",
"X-Org-Id": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'X-Org-Id': '<api-key>'}
};
fetch('https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-Auth-Token: <api-key>",
"X-Org-Id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("X-Org-Id", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"payslipContentVersion": 123,
"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>",
"submissionDownloadUrl": null,
"previewDownloadUrl": null,
"lateReason": 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
},
"pensionRefundsByType": {
"ReliefAtSource": 146.76
},
"employerPensionRefundsByType": {
"ReliefAtSource": 110.07
},
"qualifyingEarningsForPension": 0,
"apprenticeshipLevy": 1.53,
"employmentAllowance": 0,
"apprenticeshipLevyAllowance": 0,
"statutoryRecovery": {
"StatutoryMaternityPay": {
"reclaimed": 100,
"nicCompensationRecovered": 8.5
}
},
"isEmpty": false
},
"statutoryPaymentsReclaims": {
"SSP": {
"amount": 100,
"type": "StatutorySickPay"
},
"SMP": {
"amount": 150,
"type": "StatutoryMaternityPay"
}
}
},
"provisionalAllowances": {
"employmentAllowance": 1250,
"apprenticeshipLevyAllowance": 1250
}
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}Authorizations
Access token obtained from OAuth2 client credentials flow
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).
Path Parameters
The ID of the payroll configuration to use.
Query Parameters
Optional override for the payment date (format: yyyy-MM-dd).
Response
Payroll run created successfully
Increments when payslip content changes, so consumers can detect a rebuild.
The organisation ID
Example:
"LOAD_TEST"
The payroll config ID
Example:
"01JNR9P81W74HYCN35X1EEFDZE"
The payment date in format yyyy-mm-dd
Example:
"2024-05-06"
The year in format yyyy
Example:
2024
The period in format mm
Example:
"2"
The pay frequency, Valid values: 'Annual', 'Monthly', 'FourWeekly', 'Fortnightly', 'Weekly', 'Daily'.
Available options:
Annual, Monthly, FourWeekly, Fortnightly, Weekly, Daily, Quarterly, BiAnnually Example:
"Monthly"
The start date of the tax period in format yyyy-mm-dd
Example:
"2024-05-06"
The end date of the tax period in format yyyy-mm-dd
Example:
"2024-06-05"
The start date of the pay period in format yyyy-mm-dd
Example:
"2024-05-01"
The end date of the pay period in format yyyy-mm-dd
Example:
"2024-05-31"
The status of the payroll run, Valid values: 'Completed', 'Processing'.
Available options:
Completed, Processing, Open Example:
"Completed"
The status of the payroll run, Valid values: "Locked", "Unlocked".
Available options:
Locked, Unlocked Example:
"Locked"
The total number of employees in the payroll run, including employees with no payroll line items.
Example:
10
The total number of employees in the payroll run that have successfully been processed.
Example:
10
The total number of employees in the payroll run that have failed to be processed.
Example:
0
The user ID of who created the payroll run
Example:
"System"
The date and time the payroll run was created
Example:
"2025-03-21T14:17:16.126Z"
The user ID of who updated the payroll run
Example:
"System"
The date and time the payroll run was updated
Example:
"2025-03-21T14:17:19.320Z"
The date and time the payroll run was completed
Example:
"2025-03-21T14:17:19.320Z"
The user ID of who locked the payroll run
Example:
"System"
The HMRC details for the payroll run
Show child attributes
Show child attributes
The balances for the payroll run
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Create the next payroll run for a given payroll configuration
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next"
headers = {
"X-Auth-Token": "<api-key>",
"X-Org-Id": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'X-Org-Id': '<api-key>'}
};
fetch('https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-Auth-Token: <api-key>",
"X-Org-Id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("X-Org-Id", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/payroll/{payrollConfigId}/next")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"payslipContentVersion": 123,
"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>",
"submissionDownloadUrl": null,
"previewDownloadUrl": null,
"lateReason": 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
},
"pensionRefundsByType": {
"ReliefAtSource": 146.76
},
"employerPensionRefundsByType": {
"ReliefAtSource": 110.07
},
"qualifyingEarningsForPension": 0,
"apprenticeshipLevy": 1.53,
"employmentAllowance": 0,
"apprenticeshipLevyAllowance": 0,
"statutoryRecovery": {
"StatutoryMaternityPay": {
"reclaimed": 100,
"nicCompensationRecovered": 8.5
}
},
"isEmpty": false
},
"statutoryPaymentsReclaims": {
"SSP": {
"amount": 100,
"type": "StatutorySickPay"
},
"SMP": {
"amount": 150,
"type": "StatutoryMaternityPay"
}
}
},
"provisionalAllowances": {
"employmentAllowance": 1250,
"apprenticeshipLevyAllowance": 1250
}
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {},
"metadata": {
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
}
]
}