Payroll lines
Upload payroll lines
Uploads a list of payroll lines to the system. The system will attempt to process each line and return a list of validation issues for any lines that fail. The successful lines will be returned in the response. The combination of employeeID and id must be unique. There’s a hard limit of 100 items per request. In addition to the input data, the response contain an additional field ‘payrollDate’ - which corresponds to the date that will be considered for the payroll process. The payrollDate will always be populated - either with the date in the input - or with the very next yet unlocked date, in case the period for the given date is already locked. On HMRC submission, the system will use the date as reference to the period. Sending an id that matches an existing line item updates (fully replaces) that line item; if the existing line item belongs to an already locked period, the request is rejected with a 409 and no lines are written.
POST
/
payroll
/
line
/
{employeeId}
Upload payroll lines
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId} \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>' \
--data '
[
{
"date": "<string>",
"units": 123,
"payRate": 123,
"payElementId": "<string>",
"id": "<string>",
"clientId": "<string>",
"poNumber": "PO-2025-001",
"description": "<string>",
"unitType": "Amount",
"chargeRate": 123,
"chargeUnits": 1,
"chargeValue": 100,
"chargeDescription": "<string>",
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"attachments": [
{
"filename": "invoice.pdf",
"contentType": "application/pdf",
"fileSize": 102400
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"billingStatus": "None",
"paymentAfterLeavingPattern": "Irregular"
}
]
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}"
payload = [
{
"date": "<string>",
"units": 123,
"payRate": 123,
"payElementId": "<string>",
"id": "<string>",
"clientId": "<string>",
"poNumber": "PO-2025-001",
"description": "<string>",
"unitType": "Amount",
"chargeRate": 123,
"chargeUnits": 1,
"chargeValue": 100,
"chargeDescription": "<string>",
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"eligibility": { "courtOrders": {
"cmsDeo": True,
"dea": True,
"aeoPriority": False,
"aeoNonPriority": False,
"ctaeo": False,
"ea": False,
"mcaeo": False
} },
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"attachments": [
{
"filename": "invoice.pdf",
"contentType": "application/pdf",
"fileSize": 102400
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"billingStatus": "None",
"paymentAfterLeavingPattern": "Irregular"
}
]
headers = {
"X-Auth-Token": "<api-key>",
"X-Org-Id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-Token': '<api-key>',
'X-Org-Id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify([
{
date: '<string>',
units: 123,
payRate: 123,
payElementId: '<string>',
id: '<string>',
clientId: '<string>',
poNumber: 'PO-2025-001',
description: '<string>',
unitType: 'Amount',
chargeRate: 123,
chargeUnits: 1,
chargeValue: 100,
chargeDescription: '<string>',
tags: [{name: 'FullTime', group: 'EmploymentType', value: 'FullTime'}],
eligibility: {
courtOrders: {
cmsDeo: true,
dea: true,
aeoPriority: false,
aeoNonPriority: false,
ctaeo: false,
ea: false,
mcaeo: false
}
},
paymentDetails: {
accountName: 'CMS Central Account',
accountNumber: '12345678',
sortCode: '12-34-56',
paymentReference: 'CMS-2025-UK01',
paymentCategory: 'CourtOrders'
},
attachments: [{filename: 'invoice.pdf', contentType: 'application/pdf', fileSize: 102400}],
attachmentUploadUrls: [
{
attachmentId: '<string>',
filename: '<string>',
uploadUrl: '<string>',
expiresAt: '2023-11-07T05:31:56Z'
}
],
invoiceId: 'INV-001',
billingStatus: 'None',
paymentAfterLeavingPattern: 'Irregular'
}
])
};
fetch('https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}', 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/line/{employeeId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'date' => '<string>',
'units' => 123,
'payRate' => 123,
'payElementId' => '<string>',
'id' => '<string>',
'clientId' => '<string>',
'poNumber' => 'PO-2025-001',
'description' => '<string>',
'unitType' => 'Amount',
'chargeRate' => 123,
'chargeUnits' => 1,
'chargeValue' => 100,
'chargeDescription' => '<string>',
'tags' => [
[
'name' => 'FullTime',
'group' => 'EmploymentType',
'value' => 'FullTime'
]
],
'eligibility' => [
'courtOrders' => [
'cmsDeo' => true,
'dea' => true,
'aeoPriority' => false,
'aeoNonPriority' => false,
'ctaeo' => false,
'ea' => false,
'mcaeo' => false
]
],
'paymentDetails' => [
'accountName' => 'CMS Central Account',
'accountNumber' => '12345678',
'sortCode' => '12-34-56',
'paymentReference' => 'CMS-2025-UK01',
'paymentCategory' => 'CourtOrders'
],
'attachments' => [
[
'filename' => 'invoice.pdf',
'contentType' => 'application/pdf',
'fileSize' => 102400
]
],
'attachmentUploadUrls' => [
[
'attachmentId' => '<string>',
'filename' => '<string>',
'uploadUrl' => '<string>',
'expiresAt' => '2023-11-07T05:31:56Z'
]
],
'invoiceId' => 'INV-001',
'billingStatus' => 'None',
'paymentAfterLeavingPattern' => 'Irregular'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}"
payload := strings.NewReader("[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("X-Org-Id", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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/line/{employeeId}")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}")
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>'
request["Content-Type"] = 'application/json'
request.body = "[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]"
response = http.request(request)
puts response.read_body{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
},
"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>"
}
]
}
],
"messageToken": "<string>"
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"totalItems": 123,
"totalFailed": 123,
"failedItems": [
{
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
}
],
"successfulItems": [
{
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
}
]
},
"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>"
}
]
}
],
"messageToken": "<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>"
}
]
}
],
"messageToken": "<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>"
}
]
}
],
"messageToken": "<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
Body
application/json
Available options:
Hour, Day, Week, Month, Year, Fixed, Informational, Percentage The ID of the pay element associated with this payroll line.
Optional unique identifier for the payroll line
Purchase order number for billing purposes
Example:
"PO-2025-001"
The unit type for calculation. Amount uses payRate * units, Percentage uses payRate * (units / 100)
Available options:
Amount, Percentage Example:
1
The charge value times the charge units
Example:
100
Charge description for billing; when not provided and clientId is set, defaults to the pay description.
Show child attributes
Show child attributes
Eligibility flags for this payroll line (court orders, pensions, etc.)
Show child attributes
Show child attributes
Example:
{
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
}
Payment details (BACS information) that can override default employee bank account
Show child attributes
Show child attributes
Attachment metadata to include when creating the payroll line item (optional, only used during batch upload)
Show child attributes
Show child attributes
Pre-signed S3 URLs for uploading attachments (only present when attachments were provided in the request)
Show child attributes
Show child attributes
The ID of the invoice associated with the payroll line item
Example:
"INV-001"
The billing status of the payroll line item
Available options:
None, Accrued, Invoiced Example:
"None"
Which National Insurance earnings period this payment takes when it is made after the employment has ended. Only read on a payment after leaving, and ignored entirely for anyone who has not left. Irregular (accrued holiday, an unexpected bonus, arrears after a backdated pay award, a late commission or service charge) is charged on weekly thresholds; Regular (a payment they were expecting on their usual cycle, such as an expected bonus) keeps the employee's usual earnings period. Per CWG2 section 1.14 and NIM08400/NIM08410. Omitting it means Irregular, which is the safe default because the other direction understates NI. National Insurance is charged once per payslip, so a single Irregular payment puts the whole payslip on weekly thresholds.
Available options:
Irregular, Regular Example:
"Irregular"
Was this page helpful?
⌘I
Upload payroll lines
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId} \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>' \
--data '
[
{
"date": "<string>",
"units": 123,
"payRate": 123,
"payElementId": "<string>",
"id": "<string>",
"clientId": "<string>",
"poNumber": "PO-2025-001",
"description": "<string>",
"unitType": "Amount",
"chargeRate": 123,
"chargeUnits": 1,
"chargeValue": 100,
"chargeDescription": "<string>",
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"attachments": [
{
"filename": "invoice.pdf",
"contentType": "application/pdf",
"fileSize": 102400
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"billingStatus": "None",
"paymentAfterLeavingPattern": "Irregular"
}
]
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}"
payload = [
{
"date": "<string>",
"units": 123,
"payRate": 123,
"payElementId": "<string>",
"id": "<string>",
"clientId": "<string>",
"poNumber": "PO-2025-001",
"description": "<string>",
"unitType": "Amount",
"chargeRate": 123,
"chargeUnits": 1,
"chargeValue": 100,
"chargeDescription": "<string>",
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"eligibility": { "courtOrders": {
"cmsDeo": True,
"dea": True,
"aeoPriority": False,
"aeoNonPriority": False,
"ctaeo": False,
"ea": False,
"mcaeo": False
} },
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"attachments": [
{
"filename": "invoice.pdf",
"contentType": "application/pdf",
"fileSize": 102400
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"billingStatus": "None",
"paymentAfterLeavingPattern": "Irregular"
}
]
headers = {
"X-Auth-Token": "<api-key>",
"X-Org-Id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-Token': '<api-key>',
'X-Org-Id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify([
{
date: '<string>',
units: 123,
payRate: 123,
payElementId: '<string>',
id: '<string>',
clientId: '<string>',
poNumber: 'PO-2025-001',
description: '<string>',
unitType: 'Amount',
chargeRate: 123,
chargeUnits: 1,
chargeValue: 100,
chargeDescription: '<string>',
tags: [{name: 'FullTime', group: 'EmploymentType', value: 'FullTime'}],
eligibility: {
courtOrders: {
cmsDeo: true,
dea: true,
aeoPriority: false,
aeoNonPriority: false,
ctaeo: false,
ea: false,
mcaeo: false
}
},
paymentDetails: {
accountName: 'CMS Central Account',
accountNumber: '12345678',
sortCode: '12-34-56',
paymentReference: 'CMS-2025-UK01',
paymentCategory: 'CourtOrders'
},
attachments: [{filename: 'invoice.pdf', contentType: 'application/pdf', fileSize: 102400}],
attachmentUploadUrls: [
{
attachmentId: '<string>',
filename: '<string>',
uploadUrl: '<string>',
expiresAt: '2023-11-07T05:31:56Z'
}
],
invoiceId: 'INV-001',
billingStatus: 'None',
paymentAfterLeavingPattern: 'Irregular'
}
])
};
fetch('https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}', 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/line/{employeeId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'date' => '<string>',
'units' => 123,
'payRate' => 123,
'payElementId' => '<string>',
'id' => '<string>',
'clientId' => '<string>',
'poNumber' => 'PO-2025-001',
'description' => '<string>',
'unitType' => 'Amount',
'chargeRate' => 123,
'chargeUnits' => 1,
'chargeValue' => 100,
'chargeDescription' => '<string>',
'tags' => [
[
'name' => 'FullTime',
'group' => 'EmploymentType',
'value' => 'FullTime'
]
],
'eligibility' => [
'courtOrders' => [
'cmsDeo' => true,
'dea' => true,
'aeoPriority' => false,
'aeoNonPriority' => false,
'ctaeo' => false,
'ea' => false,
'mcaeo' => false
]
],
'paymentDetails' => [
'accountName' => 'CMS Central Account',
'accountNumber' => '12345678',
'sortCode' => '12-34-56',
'paymentReference' => 'CMS-2025-UK01',
'paymentCategory' => 'CourtOrders'
],
'attachments' => [
[
'filename' => 'invoice.pdf',
'contentType' => 'application/pdf',
'fileSize' => 102400
]
],
'attachmentUploadUrls' => [
[
'attachmentId' => '<string>',
'filename' => '<string>',
'uploadUrl' => '<string>',
'expiresAt' => '2023-11-07T05:31:56Z'
]
],
'invoiceId' => 'INV-001',
'billingStatus' => 'None',
'paymentAfterLeavingPattern' => 'Irregular'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}"
payload := strings.NewReader("[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
req.Header.Add("X-Org-Id", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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/line/{employeeId}")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/payroll/line/{employeeId}")
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>'
request["Content-Type"] = 'application/json'
request.body = "[\n {\n \"date\": \"<string>\",\n \"units\": 123,\n \"payRate\": 123,\n \"payElementId\": \"<string>\",\n \"id\": \"<string>\",\n \"clientId\": \"<string>\",\n \"poNumber\": \"PO-2025-001\",\n \"description\": \"<string>\",\n \"unitType\": \"Amount\",\n \"chargeRate\": 123,\n \"chargeUnits\": 1,\n \"chargeValue\": 100,\n \"chargeDescription\": \"<string>\",\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"eligibility\": {\n \"courtOrders\": {\n \"cmsDeo\": true,\n \"dea\": true,\n \"aeoPriority\": false,\n \"aeoNonPriority\": false,\n \"ctaeo\": false,\n \"ea\": false,\n \"mcaeo\": false\n }\n },\n \"paymentDetails\": {\n \"accountName\": \"CMS Central Account\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"12-34-56\",\n \"paymentReference\": \"CMS-2025-UK01\",\n \"paymentCategory\": \"CourtOrders\"\n },\n \"attachments\": [\n {\n \"filename\": \"invoice.pdf\",\n \"contentType\": \"application/pdf\",\n \"fileSize\": 102400\n }\n ],\n \"attachmentUploadUrls\": [\n {\n \"attachmentId\": \"<string>\",\n \"filename\": \"<string>\",\n \"uploadUrl\": \"<string>\",\n \"expiresAt\": \"2023-11-07T05:31:56Z\"\n }\n ],\n \"invoiceId\": \"INV-001\",\n \"billingStatus\": \"None\",\n \"paymentAfterLeavingPattern\": \"Irregular\"\n }\n]"
response = http.request(request)
puts response.read_body{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
},
"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>"
}
]
}
],
"messageToken": "<string>"
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"totalItems": 123,
"totalFailed": 123,
"failedItems": [
{
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
}
],
"successfulItems": [
{
"id": "PAYLINE-001",
"clientId": "CLIENT-001",
"employeeId": "EMPLOYEE-001",
"date": "2024-05-20",
"payrollDate": "2024-07-06",
"originalValue": 123,
"canEdit": true,
"description": "Morning shift",
"unitType": "Amount",
"units": 8,
"payRate": 10.5,
"chargeRate": 15.5,
"chargeUnits": 1,
"chargeDescription": "<string>",
"payElementId": "PAYELEM-001",
"eligibility": {
"courtOrders": {
"cmsDeo": true,
"dea": true,
"aeoPriority": false,
"aeoNonPriority": false,
"ctaeo": false,
"ea": false,
"mcaeo": false
}
},
"paymentDetails": {
"accountName": "CMS Central Account",
"accountNumber": "12345678",
"sortCode": "12-34-56",
"paymentReference": "CMS-2025-UK01",
"paymentCategory": "CourtOrders"
},
"lineItemMetadata": {
"courtOrders": {
"protectedEarningsAmount": 100,
"shortfallCarryForward": 0,
"rateType": "StandardTable",
"adminFeeApplied": true,
"tableType": "A",
"remittanceReference": "REF123",
"remittanceDeadline": "5 days",
"jurisdiction": "ENGLAND",
"aeoCategory": "Priority"
}
},
"isPensionable": true,
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"attachments": [
{
"id": "<string>",
"lineItemId": "<string>",
"filename": "<string>",
"contentType": "<string>",
"fileSize": 123,
"uploadedDate": "2023-11-07T05:31:56Z",
"uploadedBy": "<string>",
"downloadUrl": "<string>",
"downloadUrlExpiresAt": "2023-11-07T05:31:56Z"
}
],
"attachmentUploadUrls": [
{
"attachmentId": "<string>",
"filename": "<string>",
"uploadUrl": "<string>",
"expiresAt": "2023-11-07T05:31:56Z"
}
],
"invoiceId": "INV-001",
"creditNoteId": "CN-001",
"billingStatus": "None",
"poNumber": "PO-12345",
"paymentAfterLeavingPattern": "Irregular"
}
]
},
"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>"
}
]
}
],
"messageToken": "<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>"
}
]
}
],
"messageToken": "<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>"
}
]
}
],
"messageToken": "<string>"
}