Developers
Not writing code? To use Flowstate from an AI assistant, see Flowstate in Claude or Flowstate in ChatGPT.
| Surface | Use it for | Auth |
|---|---|---|
| REST API | Reading and writing employees, contractors, vacancies, teams, projects, allocations, pay history, custom attributes and functional groups; pushing business metric readings | API key |
| MCP server | Querying Flowstate and making changes, including inside scenarios, from any MCP client | OAuth, per person |
| Outbound webhooks | A signed HTTP call when a record changes | Signature |
| Custom integrations | Your own code running inside Flowstate on a schedule or on change | Runs in Flowstate |
HR systems sync in two ways: a custom integration that pulls on a schedule (recipe and per-system notes), or your integration platform writing to the REST API as changes happen (recipe). Supported systems and how each connects: Connect your HR system.
REST API
Base URL
https://{tenant}.flowstate.inc/api/v1/org/{orgId}{tenant}.flowstate.inc is the host you sign in to. {orgId} is your organisation’s ID. A key works only for its own organisation; any other orgId returns 403.
First request
- Create a key at Settings → Users & Access → API Keys → Create API Key with the View Employees permission. See Authentication.
- List one employee:
curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?limit=1" \
-H "Authorization: Bearer $FLOWSTATE_API_KEY"{
"data": [
{
"id": "cmmy2ye2iyuq66uq2iay2miyi",
"externalId": "EMP-0042",
"firstName": "Jane",
"lastName": "Chen",
"email": "jane.chen@example.com",
"startDate": "2024-03-15T00:00:00.000Z",
"endDate": null,
"managerId": null,
"jobRoleId": "caa2mi6uiy66ma22mmeaeu2e6",
"geographyId": "cuay2eqyymqe6y2ui26q6ieia",
"createdAt": "2024-03-01T09:12:44.000Z",
"updatedAt": "2026-08-30T16:02:10.000Z"
}
],
"meta": { "page": 1, "limit": 1, "total": 142, "hasNextPage": true }
}Records carry more fields than shown here; each resource page lists them.
Conventions
| Content type | Send Content-Type: application/json on every request with a body. |
| Envelope | Single record: { "data": { … } }. List: { "data": [ … ], "meta": { … } }. Error: { "error": { "code", "message", … } }; see Errors. |
| Status codes | 200 read, update, delete, vacancy fill · 201 create. |
| Delete | 200 with { "data": { "id": "…", "deleted": true } }. |
| IDs | Any {id} in a path, and reference fields such as managerId, teamId and projectId, accept the Flowstate ID or your externalId. A value of 24–25 lowercase letters and digits starting with a letter is read as a Flowstate ID; anything else as an externalId. So an externalId can’t take that shape, and must be unique per resource type in your organisation. |
| Dates | Send ISO 8601 (2026-07-01 or a full timestamp). Responses return timestamps (2026-07-01T00:00:00.000Z), except functional groups, which use YYYY-MM-DD. |
| Currency | ISO 4217, upper case (GBP). |
| Partial updates | PATCH changes only the fields you send. Send null to clear a nullable field. |
| Pagination | page and limit on most lists; see Pagination, sorting and search. |
| Scenarios | REST reads and writes live data, except functional groups. See Scenarios. |
OpenAPI
Both are public; no key needed.
| OpenAPI 3.0 (JSON) | https://{tenant}.flowstate.inc/api/v1/openapi.json |
| Swagger UI | https://{tenant}.flowstate.inc/api/v1/docs |
Limits
| Limit | Value |
|---|---|
limit on paged lists | 1–100 |
| Request body | 1 MB |
Readings per POST /business-metrics/readings | 1,000 |
POST /business-metrics/readings | 120 requests a minute per key |
| API key lifetime | 90 days maximum |
| MCP server | 100 requests a minute per person; see MCP rate limiting |
Handle 429 from any endpoint by waiting the Retry-After seconds.
Reference
Guides — Authentication · Errors · Pagination, sorting and search · Scenarios · Recipes · API changelog
People and teams — Employees · Contractors · Vacancies · Teams · Salary adjustments · Contractor rate adjustments · Functional groups
Projects and allocations — Projects · Assignments · Custom attributes
Metrics — Business metrics
Events and extensions — Outbound webhooks · Custom integrations
AI assistants and MCP — MCP server · Flowstate in Claude · Flowstate in ChatGPT
MCP-only data — Initiatives · Effort · AI usage