Employees
Update the opening balance for a specific employee
Sets the opening balance for this employment (e.g., when migrating from a different payroll system). Locked after any payslip has been finalized for the employee.
PUT
/
employees
/
{employeeId}
/
opening-balance
Update the opening balance for a specific employee
curl --request PUT \
--url https://api.sandbox.flowpayroll.ai/v1/employees/{employeeId}/opening-balance \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"openingBalance": {},
"openingBalanceDirector": {}
}
'{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"id": "emp_12345",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"secondedDetails": {
"stayStatus": "Stay183DaysOrMore",
"eEACitizen": true,
"ePM6": false
},
"alreadySentToHmrcFps": false
},
"taxCodesPerYear": {
"2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": false
}
]
},
"niDetails": {
"categoriesPerYear": {},
"nationalInsuranceNumber": "QQ123456C"
},
"phone": "+447700900123",
"maritalStatus": "Married",
"salary": 35000,
"employeeCode": "EMP001",
"secondaryEmail": "john.secondary@company.com",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"countryCode": "UK"
},
"bankAccounts": [
{
"accountNumber": "12345678",
"sortCode": "123456",
"allocationPercentage": 100,
"isPrimaryPayrollAccount": true,
"accountHolderName": "John Smith"
}
],
"studentDetails": {
"studentLoanDetails": {
"loanType": "Plan2",
"startDate": "2010-09-01",
"endDate": "2025-07-31"
},
"postgraduateLoanDetails": {
"loanType": "PostgraduateLoan",
"startDate": "2015-09-01",
"endDate": "2028-07-31"
}
},
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"previousEmployment": {
"2026": {
"grossTaxable": 15000,
"tax": 3000
}
},
"gender": "Male",
"secondaryPhone": "+447700900124",
"passportNumber": "123456789",
"previousNames": [
"John Doe"
],
"directorDetails": {
"directorsNICType": "Annual",
"appointmentDate": "2024-01-15",
"endDate": "2025-03-31"
},
"isIrregularEmployment": false,
"isOffPayrollWorker": false,
"workplaceDetails": {
"workplaceId": "workplace_001",
"workplaceName": "Head Office",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"countryCode": "UK"
}
},
"workingDays": {
"standardWorkingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"shiftPattern": {
"rotationStartDate": "2024-01-01",
"shifts": [
{
"name": "Morning Shift",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"durationInDays": 5,
"weekNumber": 1
},
{
"name": "Night Shift",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"durationInDays": 5,
"weekNumber": 2
}
],
"patternType": "FourOnFourOff",
"patternWeeks": 8
},
"workingPattern": "Standard"
},
"partnerDetails": {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"nationalInsuranceNumber": "QQ654321A"
},
"department": "Engineering",
"jobTitle": "Software Engineer",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": false
},
"earningsToDatePerYear": {},
"openingBalance": {},
"openingBalanceDirector": {},
"directorEarningsToDatePerYear": {},
"payrollId": "PAY123",
"createdDate": "2023-01-15T10:00:00Z",
"createdBy": "admin@company.com",
"updatedDate": "2023-06-01T12:00:00Z",
"updatedBy": "hr@company.com"
},
"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
Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Access token obtained from OAuth2 client credentials flow
Path Parameters
The ID of the employee whose opening balance is to be updated
Body
application/json
Request body for updating employee opening balance
Was this page helpful?
Update the starter details for a specific employee
Previous
Add or update a tax code for an employee
Next
⌘I
Update the opening balance for a specific employee
curl --request PUT \
--url https://api.sandbox.flowpayroll.ai/v1/employees/{employeeId}/opening-balance \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"openingBalance": {},
"openingBalanceDirector": {}
}
'{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": "<string>"
}
]
},
"content": {
"data": {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"id": "emp_12345",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"secondedDetails": {
"stayStatus": "Stay183DaysOrMore",
"eEACitizen": true,
"ePM6": false
},
"alreadySentToHmrcFps": false
},
"taxCodesPerYear": {
"2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": false
}
]
},
"niDetails": {
"categoriesPerYear": {},
"nationalInsuranceNumber": "QQ123456C"
},
"phone": "+447700900123",
"maritalStatus": "Married",
"salary": 35000,
"employeeCode": "EMP001",
"secondaryEmail": "john.secondary@company.com",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"countryCode": "UK"
},
"bankAccounts": [
{
"accountNumber": "12345678",
"sortCode": "123456",
"allocationPercentage": 100,
"isPrimaryPayrollAccount": true,
"accountHolderName": "John Smith"
}
],
"studentDetails": {
"studentLoanDetails": {
"loanType": "Plan2",
"startDate": "2010-09-01",
"endDate": "2025-07-31"
},
"postgraduateLoanDetails": {
"loanType": "PostgraduateLoan",
"startDate": "2015-09-01",
"endDate": "2028-07-31"
}
},
"tags": [
{
"name": "FullTime",
"group": "EmploymentType",
"value": "FullTime"
}
],
"previousEmployment": {
"2026": {
"grossTaxable": 15000,
"tax": 3000
}
},
"gender": "Male",
"secondaryPhone": "+447700900124",
"passportNumber": "123456789",
"previousNames": [
"John Doe"
],
"directorDetails": {
"directorsNICType": "Annual",
"appointmentDate": "2024-01-15",
"endDate": "2025-03-31"
},
"isIrregularEmployment": false,
"isOffPayrollWorker": false,
"workplaceDetails": {
"workplaceId": "workplace_001",
"workplaceName": "Head Office",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"countryCode": "UK"
}
},
"workingDays": {
"standardWorkingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"shiftPattern": {
"rotationStartDate": "2024-01-01",
"shifts": [
{
"name": "Morning Shift",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"durationInDays": 5,
"weekNumber": 1
},
{
"name": "Night Shift",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
},
"durationInDays": 5,
"weekNumber": 2
}
],
"patternType": "FourOnFourOff",
"patternWeeks": 8
},
"workingPattern": "Standard"
},
"partnerDetails": {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"nationalInsuranceNumber": "QQ654321A"
},
"department": "Engineering",
"jobTitle": "Software Engineer",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": false
},
"earningsToDatePerYear": {},
"openingBalance": {},
"openingBalanceDirector": {},
"directorEarningsToDatePerYear": {},
"payrollId": "PAY123",
"createdDate": "2023-01-15T10:00:00Z",
"createdBy": "admin@company.com",
"updatedDate": "2023-06-01T12:00:00Z",
"updatedBy": "hr@company.com"
},
"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>"
}