API Changelog

The Flowstate API follows Semantic Versioning. Breaking changes will only occur in major version bumps and will be announced well in advance.

For platform changes, see Flowstate Updates.

v1.2.0 — 2026-05-12

Contractor-filled vacancies + endDate-aware "currently filled" semantics.

For platform changes, see Flowstate Updates.

POST /vacancies/:id/fill now supports filling with a contractor. Pass fillerType: "contractor" in the request body along with name, rate, rateType, and currencyCode. The endpoint creates a contractor record with an initial rate adjustment and transfers the vacancy's assignments to the new contractor. The response wraps both branches via mutually-exclusive employee / contractor fields. Existing employee-fill callers continue to work unchanged — fillerType defaults to "employee".
Vacancy.filledByLiveContractorId — new mutually-exclusive companion to filledByLiveEmployeeId. Set automatically by the contractor-branch fill, or manually via PATCH.
Vacancy.isFilled (derived) — true when one of the filledBy* FKs is set and the filler's endDate is unset or in the future. Once the filler's endDate passes, the vacancy is treated as open again (forecast cost resumes from that date). This replaces the previous "filledByLiveEmployeeId IS NULL" check throughout the forecast model.
Integration hook surface for positions — Custom-integration hooks that emit vacancy records can now use filledBy: { externalId } (or the shorthand filledByExternalId). The sync layer resolves the externalId against both live employees and live contractors and sets the appropriate FK. See Custom Integrations → Vacancies.

Vacancy filtering semantics — Default vacancy listings now hide currently-filled vacancies; pass excludeFilled=false to include them. Cost forecast views suppress a vacancy's cost only while its filler is active (matching isFilled), then resume contributing cost once the filler's endDate passes.

Custom attributes, nested writes, and vacancy fill.

For platform changes, see Flowstate Updates.

Custom attributes — Define custom fields on employees, contractors, vacancies, teams, and projects via GET/POST/PATCH/DELETE /custom-attributes. Custom attribute values are returned on all resource endpoints and can be set during create and update operations.
Nested create and update — Create or update child records inline. For example, create an employee and their team assignment in a single POST /employees request by including an assignments array in the body.
Vacancy fill endpoint — POST /vacancies/:id/fill converts a vacancy into an active employee or contractor record, closing the vacancy and transferring its assignments.
?include= support — Use ?include=assignments,team,project on any resource endpoint to embed related records in the response, reducing round trips.
Cost centre filter — All list endpoints now accept costCentreId as a filter parameter.

Work Types renamed to Resource Types — The /work-types endpoint is now /resource-types. The previous path continues to work but is deprecated and will be removed in v2.0.0.

Initial public release of the Flowstate Developer API.

Employees — Full CRUD for employee records with salary, role, and geography data
Contractors — Full CRUD for external contractors with rate and contract period tracking
Vacancies — Full CRUD for open positions with salary ranges and hiring pipeline status
Teams — Full CRUD for organizational teams with hierarchy support
Projects — Full CRUD for projects with timelines and cost estimates
Assignments — Unified assignment model for employee, contractor, vacancy, and team allocations to teams and projects
Cost Centres — Full CRUD for cost centre management
Value Streams — Full CRUD for value stream organization
Work Types — Full CRUD for work type classification
Drivers — Full CRUD for strategic project drivers
Lifecycle Stages — Full CRUD for project lifecycle stage management
Exchange Rates — Full CRUD for currency conversion rates
Locations — Full CRUD for geographic location management
Scenario support — Pass scenarioId to any endpoint to operate within a what-if scenario
Pagination — Consistent page-based pagination with page, limit, search, sortBy, and sortDir
Authentication — API key-based authentication with scoped permissions
Error handling — Structured error responses with error codes and unique error IDs