Skip to main content
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

X-Auth-Token
string
header
required

Access token obtained from OAuth2 client credentials flow

Path Parameters

employeeId
string
required

The ID of the employee whose opening balance is to be updated

Body

application/json

Request body for updating employee opening balance

openingBalance
object

Opening balance for this employment from a different payroll system (migration).

openingBalanceDirector
object

Opening balance for director earnings from a different payroll system (migration). Only NI-relevant fields.

Response

Employee opening balance was successfully updated

message
object
content
object
validationIssues
object[]
messageToken
string