Positions

A position is a seat in a group: the "Senior Engineer" seat in Card Issuing, say. It expresses the demand for a person — how much of one, from when, reporting to whom — independently of whoever happens to fill it. A seat can be open, filled, or earmarked for a vacancy you are recruiting for.

An occupant is the person filling a seat for a dated period. One seat can be held by different people over time, and by more than one person at once when each takes a share of it.

What a position holds

Field	What it is
Name	The seat's name, e.g. "Staff Engineer".
Group	The group it belongs to. Fixed for the seat's life.
Required FTE	How much of a person the seat needs: above 0 and at most 1. See FTE.
Reports to	Optionally, another position in the same group. Draws the reporting lines on the Structure chart.
Job role	Optionally, one of your organisation's job roles.
Start and end date	The days the seat exists for. No end date means ongoing.
Description, external ID, custom attributes	As for groups.

FTE: what the numbers mean

FTE is a share of a full-time person. 1 is full time; 0.5 is half.

• A position's required FTE is the demand: what the seat needs to be fully staffed.
• An occupancy's FTE is the supply: how much of the seat that person takes. A full-time person in a full-time seat is 1. Two people sharing a seat might be 0.6 and 0.4.
• A seat is short when its occupants' shares on the As-of day add up to less than its required FTE. The group's FTE gap is the total shortfall across its seats, and is what the amber dot in the list reports.
• A person can hold at most 1.0 FTE across all their seats at once. Employees and contractors have full-time capacity; a vacancy's capacity is its configured FTE. Flowstate refuses an occupancy that would push a seat over its required FTE or a person over their capacity — including overlapping periods, so a replacement starting a day early is caught.

Functional FTE is independent of project allocations. Someone allocated 100% to a project can still hold a 1.0 seat.

Creating a position

Open the group and click Add position at the top of its page, or move the pointer towards the bottom of the Structure chart: a dashed Add position card appears beneath the last row — click it. Right-clicking the group's row in the list offers Add position too.

Give the seat a name and its required FTE; optionally a job role, a description, dates, and the position it reports to.

Filling a position

Click the position's card on the Structure chart to open it in the panel beside the page, then click Fill position. Choose whether you are placing an employee, a contractor or a vacancy, search for them, set the share of the seat they take, and the dates. Leave the end date empty for an open-ended arrangement. Right-clicking a card offers Fill position directly, with the directory to search chosen in the submenu.

A vacancy in a seat counts as an arrival on its start date, so recruiting shows up in the 30-day signals and the schedule before anyone is hired.

Replacing or ending an occupant

Open the position and go to its Occupants tab: everyone who has held the seat, split into Current, Upcoming and Past, each with Edit and Move.

• Someone leaves: edit their occupancy and set its end date.
• Someone is replaced: end the current occupancy, then fill the seat again with the new person from the following day. A replacement who starts next month is visible now under Upcoming.
• Someone's share changes: edit the occupancy's FTE from the day it changes; or end it and create a new one if you want the change dated separately.
• Someone moves to another seat: choose Move on their occupancy, pick the destination seat, and the day it applies from. The old occupancy ends the day before; the new one starts on that day.

The seat and the person on an occupancy never change: that is what keeps the history honest. End it and create the next one instead.

Changing who a position reports to

On the Structure chart, take a card by its grip (the six-dot handle on its left) and drop it onto the card it should report to. Drop it on the Top level strip so it reports to nobody. The change applies from the As-of day, and the earlier reporting line is kept for earlier days.

The position's panel has a Reports to picker that does the same thing, and right-clicking a card offers Change reporting line. A position can only report to a position in the same group, and never to itself or to one of its own reports.

Expiring and retiring positions

A position can carry an end date: the day the seat stops existing. Use it for a fixed-term role, a secondment seat, or a seat being closed in a restructure. From that day the seat leaves the chart, the figures and the schedule; earlier days still show it, and any occupancy has to end by then. The card shows "Ends {date}" while the seat is still open, and the schedule marks the position ending.

To retire a seat today, right-click its card and choose Edit position (or choose Edit position in its panel), then set the end date. Nothing is deleted. A seat that should move to another group is retired and re-created there.

Doing it from Claude

Add a seat

Add a full-time Staff Engineer position to Card Issuing, starting 1 October.

add_functional_position { "functionalGroupId": "<team id>", "name": "Staff Engineer",
                          "requiredFte": 1, "startDate": "2026-10-01" }

Fill it

Put Fatima Al-Hassan in the Staff Engineer seat from 1 October, full time.

fill_functional_position { "functionalPositionId": "<seat id>", "employeeId": "<Fatima's id>",
                           "fte": 1, "startDate": "2026-10-01" }

Exactly one of employeeId, contractorId or vacancyId is given.

Mark a departure

Fatima leaves the seat on 25 September.

update_functional_assignment { "functionalAssignmentId": "<occupancy id>", "functionalPositionId": "<seat id>",
                               "employeeId": "<Fatima's id>", "fte": 1,
                               "startDate": "2026-04-01", "endDate": "2026-09-25" }

Change a reporting line from a date

From 1 November the Staff Engineer reports to the Engineering Manager seat.

move_functional_position { "kind": "POSITION", "id": "<staff engineer seat id>",
                           "targetPositionId": "<engineering manager seat id>", "effectiveDate": "2026-11-01" }

Use "kind": "ASSIGNMENT" with an occupancy id to move a person to another seat instead.

Close a seat

The Legacy Statements analyst seat ends on 31 December.

update_functional_position { "functionalPositionId": "<seat id>", "functionalGroupId": "<team id>",
                             "name": "Analyst", "requiredFte": 1, "startDate": "2024-01-01", "endDate": "2026-12-31" }

Updates are full replacements; send every field you want to keep.

REST

Under /api/v1/functional-groups:

Method and path	Purpose
GET /:id/positions?asOf=	The seats in a group on one day, with occupants.
POST /positions and PUT /positions/:id	Create a seat; replace its details (including its end date).
POST /assignments and PUT /assignments/:id	Fill a seat; change an occupancy's share or dates.
POST /structure/move	Change a reporting line, or move an occupant to another seat, from a date.

See the API reference for shapes. There is no delete endpoint: seats and occupancies are ended with an end date.