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.

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>' \
  --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"
  }
]
'

{
  "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"
    },
    "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

X-Auth-Token

string

header

required

Access token obtained from OAuth2 client credentials flow

Path Parameters

employeeId

string

required

Body

application/json

date

string

required

unitName

enum<string>

required

Available options:

Hour,

Day,

Week,

Month,

Year,

Fixed,

Informational,

Percentage

units

number

required

payRate

number

required

payElementId

string

required

The ID of the pay element associated with this payroll line.

string

Optional unique identifier for the payroll line

clientId

string

poNumber

string | null

Purchase order number for billing purposes

Example:

"PO-2025-001"

description

string

unitType

enum<string>

default:Amount

The unit type for calculation. Amount uses payRate * units, Percentage uses payRate * (units / 100)

Available options:

Amount,

Percentage

chargeRate

number

chargeUnits

number

Example:

1

chargeValue

number<decimal> | null

The charge value times the charge units

Example:

100

chargeDescription

string | null

Charge description for billing; when not provided and clientId is set, defaults to the pay description.

Response

Payroll Uploaded

message

object

Show child attributes

content

object

Show child attributes

validationIssues

object[]

Show child attributes

messageToken

string

Delete a payroll configuration

Delete a payroll line

⌘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>' \
  --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"
  }
]
'

{
  "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"
    },
    "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>"
}

Documentation Index

Authorizations

Path Parameters

Body

Response