Employees
Create a new employee
POST
/
employees
Create a new employee
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/employees \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>' \
--data '
{
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"alreadySentToHmrcFps": false,
"secondedDetails": {
"eEACitizen": true,
"ePM6": false,
"stayStatus": "Stay183DaysOrMore"
}
},
"taxCodesPerYear": {
"2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": false
}
]
},
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": {
"weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
}
}
]
}
},
"partnerDetails": {
"nationalInsuranceNumber": "QQ654321A"
},
"department": "Engineering",
"jobTitle": "Software Engineer",
"id": "emp_12345",
"payrollId": "payroll_2023_001",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": false,
"finalisedOnPayslip": false
},
"openingBalance": {},
"openingBalanceDirector": {}
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/employees"
payload = {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"alreadySentToHmrcFps": False,
"secondedDetails": {
"eEACitizen": True,
"ePM6": False,
"stayStatus": "Stay183DaysOrMore"
}
},
"taxCodesPerYear": { "2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": False
}
] },
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": { "weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": True,
"tuesday": True,
"wednesday": True,
"thursday": True,
"friday": True,
"saturday": False,
"sunday": False
}
}
] }
},
"partnerDetails": { "nationalInsuranceNumber": "QQ654321A" },
"department": "Engineering",
"jobTitle": "Software Engineer",
"id": "emp_12345",
"payrollId": "payroll_2023_001",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": False,
"finalisedOnPayslip": False
},
"openingBalance": {},
"openingBalanceDirector": {}
}
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({
name: {firstName: 'John', lastName: 'Smith', middleName: 'Edward', title: 'Mr'},
email: 'john.smith@company.com',
birthGender: 'Male',
birthDate: '1985-07-23',
hoursWorkedCategory: 'Above30Hours',
payrollConfigId: 'payroll_config_001',
starterDetails: {
startDate: '2024-01-15',
starterDeclaration: 'ThisIsMyOnlyJob',
alreadySentToHmrcFps: false,
secondedDetails: {eEACitizen: true, ePM6: false, stayStatus: 'Stay183DaysOrMore'}
},
taxCodesPerYear: {
'2025': [
{
code: '1257L',
effectiveDate: '2025-04-06',
reason: 'HMRC Update',
issuedBy: 'HMRC',
week1Month1: false
}
]
},
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: 'GB'
},
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: 'GB'
}
},
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',
explicitSchedule: {
weeks: [
{
weekCommencing: '2026-07-06',
workingDays: {
monday: true,
tuesday: true,
wednesday: true,
thursday: true,
friday: true,
saturday: false,
sunday: false
}
}
]
}
},
partnerDetails: {nationalInsuranceNumber: 'QQ654321A'},
department: 'Engineering',
jobTitle: 'Software Engineer',
id: 'emp_12345',
payrollId: 'payroll_2023_001',
leaverDetails: {
leavingDate: '2024-12-31',
reason: 'Retirement',
issuedBy: 'Employer',
reportedToHmrc: false,
finalisedOnPayslip: false
},
openingBalance: {},
openingBalanceDirector: {}
})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/employees', 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/employees",
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([
'name' => [
'firstName' => 'John',
'lastName' => 'Smith',
'middleName' => 'Edward',
'title' => 'Mr'
],
'email' => 'john.smith@company.com',
'birthGender' => 'Male',
'birthDate' => '1985-07-23',
'hoursWorkedCategory' => 'Above30Hours',
'payrollConfigId' => 'payroll_config_001',
'starterDetails' => [
'startDate' => '2024-01-15',
'starterDeclaration' => 'ThisIsMyOnlyJob',
'alreadySentToHmrcFps' => false,
'secondedDetails' => [
'eEACitizen' => true,
'ePM6' => false,
'stayStatus' => 'Stay183DaysOrMore'
]
],
'taxCodesPerYear' => [
'2025' => [
[
'code' => '1257L',
'effectiveDate' => '2025-04-06',
'reason' => 'HMRC Update',
'issuedBy' => 'HMRC',
'week1Month1' => false
]
]
],
'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' => 'GB'
],
'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' => 'GB'
]
],
'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',
'explicitSchedule' => [
'weeks' => [
[
'weekCommencing' => '2026-07-06',
'workingDays' => [
'monday' => true,
'tuesday' => true,
'wednesday' => true,
'thursday' => true,
'friday' => true,
'saturday' => false,
'sunday' => false
]
]
]
]
],
'partnerDetails' => [
'nationalInsuranceNumber' => 'QQ654321A'
],
'department' => 'Engineering',
'jobTitle' => 'Software Engineer',
'id' => 'emp_12345',
'payrollId' => 'payroll_2023_001',
'leaverDetails' => [
'leavingDate' => '2024-12-31',
'reason' => 'Retirement',
'issuedBy' => 'Employer',
'reportedToHmrc' => false,
'finalisedOnPayslip' => false
],
'openingBalance' => [
],
'openingBalanceDirector' => [
]
]),
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/employees"
payload := strings.NewReader("{\n \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\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/employees")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/employees")
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 \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\n}"
response = http.request(request)
puts response.read_body{
"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",
"alreadySentToHmrcFps": false,
"secondedDetails": {
"eEACitizen": true,
"ePM6": false,
"stayStatus": "Stay183DaysOrMore"
}
},
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": {
"weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
}
}
]
}
},
"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,
"finalisedOnPayslip": 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>"
}{
"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).
Body
application/json
Show child attributes
Show child attributes
Example:
"john.smith@company.com"
Available options:
Male, Female Example:
"Male"
Example:
"1985-07-23"
Available options:
UpTo16Hours, From16To24Hours, From24To30Hours, Above30Hours, Other Example:
"Above30Hours"
The payroll config to assign the employee to.
Example:
"payroll_config_001"
Show child attributes
Show child attributes
Tax codes for the employee per tax year
Show child attributes
Show child attributes
Example:
{
"2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": false
}
]
}
National Insurance details for the employee
Show child attributes
Show child attributes
Example:
"+447700900123"
Available options:
Single, Married, Divorced, Widowed, CivilPartnership, FormerCivilPartnership, SurvivorCivilPartnership Example:
"Married"
Example:
35000
Employee code. An optional identifier for the employee.
Example:
"EMP001"
Example:
"john.secondary@company.com"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The student details of the employee
Show child attributes
Show child attributes
Example:
{
"studentLoanDetails": {
"loanType": "Plan2",
"startDate": "2010-09-01",
"endDate": "2025-07-31"
},
"postgraduateLoanDetails": {
"loanType": "PostgraduateLoan",
"startDate": "2015-09-01",
"endDate": "2028-07-31"
}
}
Show child attributes
Show child attributes
Earnings from a previous employer in the same tax year. Used for cumulative tax calculations only. Does not affect FPS reporting.
Show child attributes
Show child attributes
Example:
{
"2026": { "grossTaxable": 15000, "tax": 3000 }
}
Example:
"Male"
Example:
"+447700900124"
Example:
"123456789"
Example:
["John Doe"]
Show child attributes
Show child attributes
Example:
false
Example:
false
Show child attributes
Show child attributes
Configuration of employee's working days
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
"Engineering"
Example:
"Software Engineer"
The unique identifier for the employee.
Example:
"emp_12345"
Payroll ID. This is the ID of the payroll that the employee is associated with when sending the FPS submission to HMRC (payId field). If not provided a new one will be created. But this can affect the submission to HMRC.
Example:
"payroll_2023_001"
Leaver details for migrating employees from another system.
Show child attributes
Show child attributes
Opening balance for this employment from a different payroll system (migration).
Show child attributes
Show child attributes
Opening balance for director earnings from a different payroll system (migration). Only NI-relevant fields.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Create a new employee
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/employees \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--header 'X-Org-Id: <api-key>' \
--data '
{
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"alreadySentToHmrcFps": false,
"secondedDetails": {
"eEACitizen": true,
"ePM6": false,
"stayStatus": "Stay183DaysOrMore"
}
},
"taxCodesPerYear": {
"2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": false
}
]
},
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": {
"weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
}
}
]
}
},
"partnerDetails": {
"nationalInsuranceNumber": "QQ654321A"
},
"department": "Engineering",
"jobTitle": "Software Engineer",
"id": "emp_12345",
"payrollId": "payroll_2023_001",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": false,
"finalisedOnPayslip": false
},
"openingBalance": {},
"openingBalanceDirector": {}
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/employees"
payload = {
"name": {
"firstName": "John",
"lastName": "Smith",
"middleName": "Edward",
"title": "Mr"
},
"email": "john.smith@company.com",
"birthGender": "Male",
"birthDate": "1985-07-23",
"hoursWorkedCategory": "Above30Hours",
"payrollConfigId": "payroll_config_001",
"starterDetails": {
"startDate": "2024-01-15",
"starterDeclaration": "ThisIsMyOnlyJob",
"alreadySentToHmrcFps": False,
"secondedDetails": {
"eEACitizen": True,
"ePM6": False,
"stayStatus": "Stay183DaysOrMore"
}
},
"taxCodesPerYear": { "2025": [
{
"code": "1257L",
"effectiveDate": "2025-04-06",
"reason": "HMRC Update",
"issuedBy": "HMRC",
"week1Month1": False
}
] },
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": { "weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": True,
"tuesday": True,
"wednesday": True,
"thursday": True,
"friday": True,
"saturday": False,
"sunday": False
}
}
] }
},
"partnerDetails": { "nationalInsuranceNumber": "QQ654321A" },
"department": "Engineering",
"jobTitle": "Software Engineer",
"id": "emp_12345",
"payrollId": "payroll_2023_001",
"leaverDetails": {
"leavingDate": "2024-12-31",
"reason": "Retirement",
"issuedBy": "Employer",
"reportedToHmrc": False,
"finalisedOnPayslip": False
},
"openingBalance": {},
"openingBalanceDirector": {}
}
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({
name: {firstName: 'John', lastName: 'Smith', middleName: 'Edward', title: 'Mr'},
email: 'john.smith@company.com',
birthGender: 'Male',
birthDate: '1985-07-23',
hoursWorkedCategory: 'Above30Hours',
payrollConfigId: 'payroll_config_001',
starterDetails: {
startDate: '2024-01-15',
starterDeclaration: 'ThisIsMyOnlyJob',
alreadySentToHmrcFps: false,
secondedDetails: {eEACitizen: true, ePM6: false, stayStatus: 'Stay183DaysOrMore'}
},
taxCodesPerYear: {
'2025': [
{
code: '1257L',
effectiveDate: '2025-04-06',
reason: 'HMRC Update',
issuedBy: 'HMRC',
week1Month1: false
}
]
},
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: 'GB'
},
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: 'GB'
}
},
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',
explicitSchedule: {
weeks: [
{
weekCommencing: '2026-07-06',
workingDays: {
monday: true,
tuesday: true,
wednesday: true,
thursday: true,
friday: true,
saturday: false,
sunday: false
}
}
]
}
},
partnerDetails: {nationalInsuranceNumber: 'QQ654321A'},
department: 'Engineering',
jobTitle: 'Software Engineer',
id: 'emp_12345',
payrollId: 'payroll_2023_001',
leaverDetails: {
leavingDate: '2024-12-31',
reason: 'Retirement',
issuedBy: 'Employer',
reportedToHmrc: false,
finalisedOnPayslip: false
},
openingBalance: {},
openingBalanceDirector: {}
})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/employees', 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/employees",
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([
'name' => [
'firstName' => 'John',
'lastName' => 'Smith',
'middleName' => 'Edward',
'title' => 'Mr'
],
'email' => 'john.smith@company.com',
'birthGender' => 'Male',
'birthDate' => '1985-07-23',
'hoursWorkedCategory' => 'Above30Hours',
'payrollConfigId' => 'payroll_config_001',
'starterDetails' => [
'startDate' => '2024-01-15',
'starterDeclaration' => 'ThisIsMyOnlyJob',
'alreadySentToHmrcFps' => false,
'secondedDetails' => [
'eEACitizen' => true,
'ePM6' => false,
'stayStatus' => 'Stay183DaysOrMore'
]
],
'taxCodesPerYear' => [
'2025' => [
[
'code' => '1257L',
'effectiveDate' => '2025-04-06',
'reason' => 'HMRC Update',
'issuedBy' => 'HMRC',
'week1Month1' => false
]
]
],
'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' => 'GB'
],
'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' => 'GB'
]
],
'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',
'explicitSchedule' => [
'weeks' => [
[
'weekCommencing' => '2026-07-06',
'workingDays' => [
'monday' => true,
'tuesday' => true,
'wednesday' => true,
'thursday' => true,
'friday' => true,
'saturday' => false,
'sunday' => false
]
]
]
]
],
'partnerDetails' => [
'nationalInsuranceNumber' => 'QQ654321A'
],
'department' => 'Engineering',
'jobTitle' => 'Software Engineer',
'id' => 'emp_12345',
'payrollId' => 'payroll_2023_001',
'leaverDetails' => [
'leavingDate' => '2024-12-31',
'reason' => 'Retirement',
'issuedBy' => 'Employer',
'reportedToHmrc' => false,
'finalisedOnPayslip' => false
],
'openingBalance' => [
],
'openingBalanceDirector' => [
]
]),
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/employees"
payload := strings.NewReader("{\n \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\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/employees")
.header("X-Auth-Token", "<api-key>")
.header("X-Org-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/employees")
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 \"name\": {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"middleName\": \"Edward\",\n \"title\": \"Mr\"\n },\n \"email\": \"john.smith@company.com\",\n \"birthGender\": \"Male\",\n \"birthDate\": \"1985-07-23\",\n \"hoursWorkedCategory\": \"Above30Hours\",\n \"payrollConfigId\": \"payroll_config_001\",\n \"starterDetails\": {\n \"startDate\": \"2024-01-15\",\n \"starterDeclaration\": \"ThisIsMyOnlyJob\",\n \"alreadySentToHmrcFps\": false,\n \"secondedDetails\": {\n \"eEACitizen\": true,\n \"ePM6\": false,\n \"stayStatus\": \"Stay183DaysOrMore\"\n }\n },\n \"taxCodesPerYear\": {\n \"2025\": [\n {\n \"code\": \"1257L\",\n \"effectiveDate\": \"2025-04-06\",\n \"reason\": \"HMRC Update\",\n \"issuedBy\": \"HMRC\",\n \"week1Month1\": false\n }\n ]\n },\n \"phone\": \"+447700900123\",\n \"maritalStatus\": \"Married\",\n \"salary\": 35000,\n \"employeeCode\": \"EMP001\",\n \"secondaryEmail\": \"john.secondary@company.com\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n },\n \"bankAccounts\": [\n {\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"123456\",\n \"allocationPercentage\": 100,\n \"isPrimaryPayrollAccount\": true,\n \"accountHolderName\": \"John Smith\"\n }\n ],\n \"studentDetails\": {\n \"studentLoanDetails\": {\n \"loanType\": \"Plan2\",\n \"startDate\": \"2010-09-01\",\n \"endDate\": \"2025-07-31\"\n },\n \"postgraduateLoanDetails\": {\n \"loanType\": \"PostgraduateLoan\",\n \"startDate\": \"2015-09-01\",\n \"endDate\": \"2028-07-31\"\n }\n },\n \"tags\": [\n {\n \"name\": \"FullTime\",\n \"group\": \"EmploymentType\",\n \"value\": \"FullTime\"\n }\n ],\n \"previousEmployment\": {\n \"2026\": {\n \"grossTaxable\": 15000,\n \"tax\": 3000\n }\n },\n \"gender\": \"Male\",\n \"secondaryPhone\": \"+447700900124\",\n \"passportNumber\": \"123456789\",\n \"previousNames\": [\n \"John Doe\"\n ],\n \"directorDetails\": {\n \"directorsNICType\": \"Annual\",\n \"appointmentDate\": \"2024-01-15\",\n \"endDate\": \"2025-03-31\"\n },\n \"isIrregularEmployment\": false,\n \"isOffPayrollWorker\": false,\n \"workplaceDetails\": {\n \"workplaceId\": \"workplace_001\",\n \"workplaceName\": \"Head Office\",\n \"address\": {\n \"line1\": \"123 Main Street\",\n \"line2\": \"Apt 4B\",\n \"city\": \"London\",\n \"county\": \"Greater London\",\n \"postcode\": \"SW1A 1AA\",\n \"countryCode\": \"GB\"\n }\n },\n \"workingDays\": {\n \"standardWorkingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"shiftPattern\": {\n \"rotationStartDate\": \"2024-01-01\",\n \"shifts\": [\n {\n \"name\": \"Morning Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 1\n },\n {\n \"name\": \"Night Shift\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n },\n \"durationInDays\": 5,\n \"weekNumber\": 2\n }\n ],\n \"patternType\": \"FourOnFourOff\",\n \"patternWeeks\": 8\n },\n \"workingPattern\": \"Standard\",\n \"explicitSchedule\": {\n \"weeks\": [\n {\n \"weekCommencing\": \"2026-07-06\",\n \"workingDays\": {\n \"monday\": true,\n \"tuesday\": true,\n \"wednesday\": true,\n \"thursday\": true,\n \"friday\": true,\n \"saturday\": false,\n \"sunday\": false\n }\n }\n ]\n }\n },\n \"partnerDetails\": {\n \"nationalInsuranceNumber\": \"QQ654321A\"\n },\n \"department\": \"Engineering\",\n \"jobTitle\": \"Software Engineer\",\n \"id\": \"emp_12345\",\n \"payrollId\": \"payroll_2023_001\",\n \"leaverDetails\": {\n \"leavingDate\": \"2024-12-31\",\n \"reason\": \"Retirement\",\n \"issuedBy\": \"Employer\",\n \"reportedToHmrc\": false,\n \"finalisedOnPayslip\": false\n },\n \"openingBalance\": {},\n \"openingBalanceDirector\": {}\n}"
response = http.request(request)
puts response.read_body{
"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",
"alreadySentToHmrcFps": false,
"secondedDetails": {
"eEACitizen": true,
"ePM6": false,
"stayStatus": "Stay183DaysOrMore"
}
},
"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": "GB"
},
"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": "GB"
}
},
"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",
"explicitSchedule": {
"weeks": [
{
"weekCommencing": "2026-07-06",
"workingDays": {
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false
}
}
]
}
},
"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,
"finalisedOnPayslip": 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>"
}{
"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>"
}