Create the next payroll run for a given payroll configuration

POST

payroll

{payrollConfigId}

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

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

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

X-Auth-Token

string

header

required

Access token obtained from OAuth2 client credentials flow

X-Org-Id

string

header

required

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

payrollConfigId

string

required

The ID of the payroll configuration to use.

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

Show child attributes

totalBalances

object

The balances for the payroll run

Show child attributes

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

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

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

Overview

Authentication API

Pay API

Statutory pay

Court orders

Holiday & leave

Pensions

Recurring line items

HMRC DPS

HMRC P-forms

Billing

Payment

Payroll journals

Reports

Create the next payroll run for a given payroll configuration

Authorizations

Path Parameters

Query Parameters

Response