Employees

Search the organisation's employees on any field

Needs permission employee:read.

Filters on any employee field (every operator a field’s type allows; tags and other repeated fields match any or all values), dated values such as the tax code and NI category as on asAt, sorting, the fields to answer, and paging with how many match in all, so a list can say “50 of 6,000”. Fields your role cannot read are neither answered nor matched. GET /employee-fields lists every field you can filter on. To see your own change straight after a write, send the employee and the updatedDate your write returned in consistentWith.

POST

employees

curl --request POST \
  --url https://api.sandbox.flowpayroll.ai/v1/employees/search \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "asAt": "2026-11-05",
  "status": "Active",
  "search": "jane",
  "filters": [
    {
      "field": "department",
      "operator": "In",
      "values": [
        "Engineering",
        "Sales"
      ]
    }
  ],
  "sort": [
    {
      "field": "starterDetails.startDate",
      "descending": true
    }
  ],
  "fields": [
    "name",
    "department",
    "taxCode"
  ],
  "limit": 100,
  "offset": 0,
  "consistentWith": [
    {
      "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
      "updatedDate": "2026-11-05T10:00:00.000Z"
    }
  ]
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/employees/search"

payload = {
    "asAt": "2026-11-05",
    "status": "Active",
    "search": "jane",
    "filters": [
        {
            "field": "department",
            "operator": "In",
            "values": ["Engineering", "Sales"]
        }
    ],
    "sort": [
        {
            "field": "starterDetails.startDate",
            "descending": True
        }
    ],
    "fields": ["name", "department", "taxCode"],
    "limit": 100,
    "offset": 0,
    "consistentWith": [
        {
            "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
            "updatedDate": "2026-11-05T10:00:00.000Z"
        }
    ]
}
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({
    asAt: '2026-11-05',
    status: 'Active',
    search: 'jane',
    filters: [{field: 'department', operator: 'In', values: ['Engineering', 'Sales']}],
    sort: [{field: 'starterDetails.startDate', descending: true}],
    fields: ['name', 'department', 'taxCode'],
    limit: 100,
    offset: 0,
    consistentWith: [
      {
        employeeId: '01JD8Y7Q3N4M5P6R7S8T9V0W1X',
        updatedDate: '2026-11-05T10:00:00.000Z'
      }
    ]
  })
};

fetch('https://api.sandbox.flowpayroll.ai/v1/employees/search', 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/search",
  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([
    'asAt' => '2026-11-05',
    'status' => 'Active',
    'search' => 'jane',
    'filters' => [
        [
                'field' => 'department',
                'operator' => 'In',
                'values' => [
                                'Engineering',
                                'Sales'
                ]
        ]
    ],
    'sort' => [
        [
                'field' => 'starterDetails.startDate',
                'descending' => true
        ]
    ],
    'fields' => [
        'name',
        'department',
        'taxCode'
    ],
    'limit' => 100,
    'offset' => 0,
    'consistentWith' => [
        [
                'employeeId' => '01JD8Y7Q3N4M5P6R7S8T9V0W1X',
                'updatedDate' => '2026-11-05T10:00:00.000Z'
        ]
    ]
  ]),
  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/search"

	payload := strings.NewReader("{\n  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\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/search")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/employees/search")

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  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": {
      "items": [
        {
          "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
          "status": "Active",
          "employee": {
            "name": {
              "firstName": "John",
              "lastName": "Smith",
              "title": "Mr",
              "initials": "<string>",
              "middleName": "Edward"
            },
            "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": {
              "nationalInsuranceNumber": "QQ123456C",
              "categoriesPerYear": {}
            },
            "phone": "<string>",
            "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",
                "accountHolderName": "John Smith",
                "isPrimaryPayrollAccount": true,
                "allocationPercentage": 100
              }
            ],
            "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": "<string>",
            "passportNumber": "123456789",
            "previousNames": [
              "John Doe"
            ],
            "directorDetails": {
              "directorsNICType": "Annual",
              "appointmentDate": "2024-01-15",
              "endDate": "2025-03-31"
            },
            "isIrregularEmployment": false,
            "isOffPayrollWorker": false,
            "workplaceDetails": {
              "workplacePostcode": "E1 6AN"
            },
            "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
                  },
                  {
                    "name": "Night Shift",
                    "workingDays": {
                      "monday": true,
                      "tuesday": true,
                      "wednesday": true,
                      "thursday": true,
                      "friday": true,
                      "saturday": false,
                      "sunday": false
                    },
                    "durationInDays": 5
                  }
                ],
                "patternType": "FourOnFourOff"
              },
              "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",
              "name": {
                "firstName": "John",
                "lastName": "Smith",
                "title": "Mr",
                "initials": "<string>",
                "middleName": "Edward"
              }
            },
            "department": "Engineering",
            "jobTitle": "Software Engineer",
            "payrollId": "PAY123",
            "payrollIdChanged": {
              "oldPayId": "<string>"
            },
            "leaverDetails": {
              "leavingDate": "2024-12-31",
              "reason": "Retirement",
              "issuedBy": "Employer",
              "reportedToHmrc": false,
              "finalisedOnPayslip": true
            },
            "isLeaver": true,
            "earningsToDatePerYear": {},
            "openingBalance": {},
            "openingBalanceDirector": {},
            "directorEarningsToDatePerYear": {},
            "salaryHistory": {
              "versions": [
                {
                  "effectiveFrom": "2026-04-06",
                  "annualSalary": 52000,
                  "createdDate": "<string>",
                  "createdBy": "<string>",
                  "updatedDate": "<string>",
                  "updatedBy": "<string>",
                  "reason": "Annual review",
                  "contractedHoursPerWeek": 37.5
                }
              ],
              "inForce": {
                "effectiveFrom": "2026-04-06",
                "annualSalary": 52000,
                "createdDate": "<string>",
                "createdBy": "<string>",
                "updatedDate": "<string>",
                "updatedBy": "<string>",
                "reason": "Annual review",
                "contractedHoursPerWeek": 37.5
              }
            },
            "createdDate": "2023-01-15T10:00:00Z",
            "createdBy": "admin@company.com",
            "updatedDate": "2023-06-01T12:00:00Z",
            "updatedBy": "hr@company.com"
          },
          "inForce": {
            "taxCode": "1257L",
            "niCategory": "A",
            "salary": 32000,
            "director": true,
            "studentLoan": "Plan2",
            "postgraduateLoan": "PostgraduateLoan"
          }
        }
      ],
      "total": 6000,
      "hasMore": true
    }
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

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).

Headers

Request-Id

string

Optional. Your id for this request: it is carried into every log line about it, so quote it when you contact support.

Body

application/json

What to match, sort and answer; an empty body lists every employee

Employees of the organisation matching every filter, a page at a time, with how many match in all.

asAt

string<date> | null

The date dated values and where each employee stands are read for, yyyy-MM-dd; today when omitted.

Example:

"2026-11-05"

status

enum<string>

Leaver: marked a leaver or left before the date. FutureLeaver: active with a leaving date on or after it. All when omitted.

Available options:

All,

Active,

Leaver,

FutureLeaver

Example:

"Active"

string | null

Name, email, employee code or payroll ID containing this, any case.

Example:

"jane"

filters

object[] | null

Every one must hold.

Show child attributes

sort

object[] | null

Then by last name and first name.

Show child attributes

fields

string[] | null

The fields to answer; a group such as address answers all of it. Everything your role can read when omitted.

Example:

["name", "department", "taxCode"]

limit

integer<int32>

At most this many, from 1 to 500.

Example:

100

offset

integer<int32>

How many matches to skip.

Example:

0

consistentWith

object[] | null

Employees you have just written: the answer waits until it reflects them, or answers 503 with Retry-After when it cannot within ten seconds.

Show child attributes

Response

Employees found

message

object

required

A readable message about the outcome and a stable token a client can branch on.

Show child attributes

content

object

The data the request returns with its metadata; left out on a response that carries no data, such as most errors.

Show child attributes

validationIssues

object[] | null

Each field the request was refused for and why; left out when the request was not refused for its fields.

Show child attributes

Search the organisation's employees on any field

curl --request POST \
  --url https://api.sandbox.flowpayroll.ai/v1/employees/search \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "asAt": "2026-11-05",
  "status": "Active",
  "search": "jane",
  "filters": [
    {
      "field": "department",
      "operator": "In",
      "values": [
        "Engineering",
        "Sales"
      ]
    }
  ],
  "sort": [
    {
      "field": "starterDetails.startDate",
      "descending": true
    }
  ],
  "fields": [
    "name",
    "department",
    "taxCode"
  ],
  "limit": 100,
  "offset": 0,
  "consistentWith": [
    {
      "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
      "updatedDate": "2026-11-05T10:00:00.000Z"
    }
  ]
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/employees/search"

payload = {
    "asAt": "2026-11-05",
    "status": "Active",
    "search": "jane",
    "filters": [
        {
            "field": "department",
            "operator": "In",
            "values": ["Engineering", "Sales"]
        }
    ],
    "sort": [
        {
            "field": "starterDetails.startDate",
            "descending": True
        }
    ],
    "fields": ["name", "department", "taxCode"],
    "limit": 100,
    "offset": 0,
    "consistentWith": [
        {
            "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
            "updatedDate": "2026-11-05T10:00:00.000Z"
        }
    ]
}
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({
    asAt: '2026-11-05',
    status: 'Active',
    search: 'jane',
    filters: [{field: 'department', operator: 'In', values: ['Engineering', 'Sales']}],
    sort: [{field: 'starterDetails.startDate', descending: true}],
    fields: ['name', 'department', 'taxCode'],
    limit: 100,
    offset: 0,
    consistentWith: [
      {
        employeeId: '01JD8Y7Q3N4M5P6R7S8T9V0W1X',
        updatedDate: '2026-11-05T10:00:00.000Z'
      }
    ]
  })
};

fetch('https://api.sandbox.flowpayroll.ai/v1/employees/search', 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/search",
  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([
    'asAt' => '2026-11-05',
    'status' => 'Active',
    'search' => 'jane',
    'filters' => [
        [
                'field' => 'department',
                'operator' => 'In',
                'values' => [
                                'Engineering',
                                'Sales'
                ]
        ]
    ],
    'sort' => [
        [
                'field' => 'starterDetails.startDate',
                'descending' => true
        ]
    ],
    'fields' => [
        'name',
        'department',
        'taxCode'
    ],
    'limit' => 100,
    'offset' => 0,
    'consistentWith' => [
        [
                'employeeId' => '01JD8Y7Q3N4M5P6R7S8T9V0W1X',
                'updatedDate' => '2026-11-05T10:00:00.000Z'
        ]
    ]
  ]),
  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/search"

	payload := strings.NewReader("{\n  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\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/search")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/employees/search")

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  \"asAt\": \"2026-11-05\",\n  \"status\": \"Active\",\n  \"search\": \"jane\",\n  \"filters\": [\n    {\n      \"field\": \"department\",\n      \"operator\": \"In\",\n      \"values\": [\n        \"Engineering\",\n        \"Sales\"\n      ]\n    }\n  ],\n  \"sort\": [\n    {\n      \"field\": \"starterDetails.startDate\",\n      \"descending\": true\n    }\n  ],\n  \"fields\": [\n    \"name\",\n    \"department\",\n    \"taxCode\"\n  ],\n  \"limit\": 100,\n  \"offset\": 0,\n  \"consistentWith\": [\n    {\n      \"employeeId\": \"01JD8Y7Q3N4M5P6R7S8T9V0W1X\",\n      \"updatedDate\": \"2026-11-05T10:00:00.000Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": {
      "items": [
        {
          "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
          "status": "Active",
          "employee": {
            "name": {
              "firstName": "John",
              "lastName": "Smith",
              "title": "Mr",
              "initials": "<string>",
              "middleName": "Edward"
            },
            "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": {
              "nationalInsuranceNumber": "QQ123456C",
              "categoriesPerYear": {}
            },
            "phone": "<string>",
            "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",
                "accountHolderName": "John Smith",
                "isPrimaryPayrollAccount": true,
                "allocationPercentage": 100
              }
            ],
            "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": "<string>",
            "passportNumber": "123456789",
            "previousNames": [
              "John Doe"
            ],
            "directorDetails": {
              "directorsNICType": "Annual",
              "appointmentDate": "2024-01-15",
              "endDate": "2025-03-31"
            },
            "isIrregularEmployment": false,
            "isOffPayrollWorker": false,
            "workplaceDetails": {
              "workplacePostcode": "E1 6AN"
            },
            "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
                  },
                  {
                    "name": "Night Shift",
                    "workingDays": {
                      "monday": true,
                      "tuesday": true,
                      "wednesday": true,
                      "thursday": true,
                      "friday": true,
                      "saturday": false,
                      "sunday": false
                    },
                    "durationInDays": 5
                  }
                ],
                "patternType": "FourOnFourOff"
              },
              "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",
              "name": {
                "firstName": "John",
                "lastName": "Smith",
                "title": "Mr",
                "initials": "<string>",
                "middleName": "Edward"
              }
            },
            "department": "Engineering",
            "jobTitle": "Software Engineer",
            "payrollId": "PAY123",
            "payrollIdChanged": {
              "oldPayId": "<string>"
            },
            "leaverDetails": {
              "leavingDate": "2024-12-31",
              "reason": "Retirement",
              "issuedBy": "Employer",
              "reportedToHmrc": false,
              "finalisedOnPayslip": true
            },
            "isLeaver": true,
            "earningsToDatePerYear": {},
            "openingBalance": {},
            "openingBalanceDirector": {},
            "directorEarningsToDatePerYear": {},
            "salaryHistory": {
              "versions": [
                {
                  "effectiveFrom": "2026-04-06",
                  "annualSalary": 52000,
                  "createdDate": "<string>",
                  "createdBy": "<string>",
                  "updatedDate": "<string>",
                  "updatedBy": "<string>",
                  "reason": "Annual review",
                  "contractedHoursPerWeek": 37.5
                }
              ],
              "inForce": {
                "effectiveFrom": "2026-04-06",
                "annualSalary": 52000,
                "createdDate": "<string>",
                "createdBy": "<string>",
                "updatedDate": "<string>",
                "updatedBy": "<string>",
                "reason": "Annual review",
                "contractedHoursPerWeek": 37.5
              }
            },
            "createdDate": "2023-01-15T10:00:00Z",
            "createdBy": "admin@company.com",
            "updatedDate": "2023-06-01T12:00:00Z",
            "updatedBy": "hr@company.com"
          },
          "inForce": {
            "taxCode": "1257L",
            "niCategory": "A",
            "salary": 32000,
            "director": true,
            "studentLoan": "Plan2",
            "postgraduateLoan": "PostgraduateLoan"
          }
        }
      ],
      "total": 6000,
      "hasMore": true
    }
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

Overview

Administration API

Email Wording API

Authentication API

Billing

Court orders

HMRC DPS

HMRC P-forms

Holiday & leave

Integrations

Pay API

Payment

Payroll journals

Pensions

Recurring line items

Reports

Salary

Statutory pay

Webhooks

Search the organisation's employees on any field

Authorizations

Headers

Body

Response