Employees

Manage employee records in your organization. Employees represent full-time and part-time staff with salary information, team memberships, and project assignments.

Endpoints

Method	Path	Description
GET	/org/:orgId/employees	List employees
GET	/org/:orgId/employees/:id	Get employee
POST	/org/:orgId/employees	Create employee
PATCH	/org/:orgId/employees/:id	Update employee
DELETE	/org/:orgId/employees/:id	Delete employee

---

List Employees

GET /org/:orgId/employees

Returns a paginated list of employees in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by first name, last name, or email
sortBy	string	lastName	Sort field (see below)
sortDir	string	asc	asc or desc
scenarioId	string	—	Scenario ID for what-if queries

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?sortBy=lastName&limit=10" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "firstName": "Jane",
      "lastName": "Chen",
      "email": "jane.chen@example.com",
      "internalEmployeeId": "EMP-1042",
      "startDate": "2024-03-15",
      "endDate": null,
      "managerId": "clx9m4n5o6p7",
      "jobRoleId": "clx9r8q7w6e5",
      "workTypeId": "clx2w3x4y5z6",
      "geographyId": "clx3g2h1j0k9",
      "defaultCurrencyCode": "USD",
      "noticeDate": null,
      "metadata": {},
      "createdAt": "2024-03-15T10:30:00Z",
      "updatedAt": "2024-06-01T14:22:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 142,
    "hasNextPage": true
  }
}

---

Get Employee

GET /org/:orgId/employees/:id

Returns a single employee by ID.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/clx1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "firstName": "Jane",
    "lastName": "Chen",
    "email": "jane.chen@example.com",
    "internalEmployeeId": "EMP-1042",
    "startDate": "2024-03-15",
    "endDate": null,
    "managerId": "clx9m4n5o6p7",
    "jobRoleId": "clx9r8q7w6e5",
    "workTypeId": "clx2w3x4y5z6",
    "geographyId": "clx3g2h1j0k9",
    "defaultCurrencyCode": "USD",
    "noticeDate": null,
    "metadata": {},
    "createdAt": "2024-03-15T10:30:00Z",
    "updatedAt": "2024-06-01T14:22:00Z"
  }
}

---

Create Employee

POST /org/:orgId/employees

Creates a new employee record.

Request Body

{
  "firstName": "Alex",
  "lastName": "Rivera",
  "email": "alex.rivera@example.com",
  "internalEmployeeId": "EMP-2001",
  "startDate": "2026-07-01",
  "jobRoleId": "clx9r8q7w6e5",
  "workTypeId": "clx2w3x4y5z6",
  "geographyId": "clx3g2h1j0k9",
  "defaultCurrencyCode": "GBP",
  "managerId": "clx9m4n5o6p7",
  "metadata": {
    "department": "Engineering"
  }
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Rivera",
    "email": "alex.rivera@example.com",
    "startDate": "2026-07-01",
    "defaultCurrencyCode": "GBP"
  }'

Example Response

{
  "data": {
    "id": "clx7n8m9k0j1h2g3",
    "firstName": "Alex",
    "lastName": "Rivera",
    "email": "alex.rivera@example.com",
    "internalEmployeeId": null,
    "startDate": "2026-07-01",
    "endDate": null,
    "managerId": null,
    "jobRoleId": null,
    "workTypeId": null,
    "geographyId": null,
    "defaultCurrencyCode": "GBP",
    "noticeDate": null,
    "metadata": {},
    "createdAt": "2026-03-11T09:15:00Z",
    "updatedAt": "2026-03-11T09:15:00Z"
  }
}

Status: 201 Created

---

Update Employee

PATCH /org/:orgId/employees/:id

Updates one or more fields on an existing employee. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/clx1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "lastName": "Chen-Rivera",
    "endDate": "2026-12-31",
    "noticeDate": "2026-09-30"
  }'

Example Response

{
  "data": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "firstName": "Jane",
    "lastName": "Chen-Rivera",
    "email": "jane.chen@example.com",
    "internalEmployeeId": "EMP-1042",
    "startDate": "2024-03-15",
    "endDate": "2026-12-31",
    "managerId": "clx9m4n5o6p7",
    "jobRoleId": "clx9r8q7w6e5",
    "workTypeId": "clx2w3x4y5z6",
    "geographyId": "clx3g2h1j0k9",
    "defaultCurrencyCode": "USD",
    "noticeDate": "2026-09-30",
    "metadata": {},
    "createdAt": "2024-03-15T10:30:00Z",
    "updatedAt": "2026-03-11T09:20:00Z"
  }
}

---

Delete Employee

DELETE /org/:orgId/employees/:id

Deletes an employee record. This operation is permanent for live data. In scenario mode, it creates a soft-delete tombstone.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees/clx1a2b3c4d5e6f7g8h9" \
  -H "Authorization: Bearer private_..."

Status: 204 No Content

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
firstName	string	Yes	Employee first name
lastName	string	Yes	Employee last name
email	string	Yes	Employee email address
internalEmployeeId	string	No	Your internal employee ID (e.g., from HRIS)
startDate	date	Yes	Employment start date (ISO 8601: YYYY-MM-DD)
endDate	date	No	Employment end date (null = currently active)
managerId	string	No	ID of the reporting manager (employee ID)
jobRoleId	string	No	ID of the job role
workTypeId	string	No	ID of the work type
geographyId	string	No	ID of the geography/location
defaultCurrencyCode	string	No	ISO 4217 currency code (e.g., USD, GBP)
noticeDate	date	No	Date the employee gave notice
metadata	object	No	Arbitrary JSON metadata (default: {})
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)