Assignments

Manage FTE allocations that link people (employees, contractors, vacancies) to teams and projects. Assignments are the core mechanism for workforce allocation -- they define how much of each person's capacity flows to each team or project over a specific time period.

New to Flowstate?

Read the Domain Model to understand how assignments connect the workforce to organizational structure and project work.

Concepts

Assignment Types

Flowstate uses a unified assignment model with four sub-resources:

Sub-resource	From	To	Description
`/assignments/employees`	Employee	Team or Project	Employee allocation
`/assignments/contractors`	Contractor	Team or Project	Contractor allocation
`/assignments/vacancies`	Vacancy	Team or Project	Vacancy allocation
`/assignments/teams`	Team	Project	Team-to-project allocation

Request vs. Response Fields

Important: Request and response schemas differ

When creating an assignment, provide either teamId or projectId (not both) to specify the target.

In the response, the API returns a normalized type field ("team" or "project") and a targetId field (the ID of the team or project) for uniform consumption.

This means: you send teamId or projectId in the request, but you read type + targetId in the response.

FTE (Full-Time Equivalent)

The fte field is a decimal representing the proportion of a full-time person:

1.0 = full-time on this assignment
0.5 = half-time
0.2 = one day per week

An employee's total FTE across all assignments can exceed 1.0 (indicating overallocation). The valid range per assignment is 0 to 10.

Time-Bounded Records

All assignments have startDate and endDate fields. The assignment is active for any date where startDate <= date <= endDate. An endDate of null means the assignment is ongoing.

Assignment Response Object

This is the shape returned by all employee, contractor, and vacancy assignment endpoints.

Field	Type	Description
`id`	`string`	Unique identifier (CUID format). System-generated. Read-only.
`type`	`string`	`"team"` or `"project"` -- whether this assignment targets a team or project.
`targetId`	`string`	ID of the target team or project.
`fte`	`number`	FTE allocation. `1.0` = full-time on this assignment.
`startDate`	`date (YYYY-MM-DD)`	Assignment start date (inclusive).
`endDate`	`date (YYYY-MM-DD) \| null`	Assignment end date (inclusive). `null` = ongoing.
`createdAt`	`datetime (ISO 8601)`	When the record was created. Read-only.
`updatedAt`	`datetime (ISO 8601)`	When the record was last modified. Read-only.

Employee Assignments

Endpoints

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

List Employee Assignments

GET /org/:orgId/assignments/employees

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`20`	Records per page. Min 1, max 100.
`employeeId`	string	--	Filter by employee ID.
`targetId`	string	--	Filter by target team or project ID.
`type`	string	--	Filter by type: `"team"` or `"project"`.
`sortBy`	string	`startDate`	Field to sort by.
`sortDir`	string	`asc`	`asc` or `desc`.
`scenarioId`	string	--	Scenario ID for what-if queries.

Example Request

bash

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees?employeeId=clx1a2b3c4d5e6f7g8h9&type=team" \
  -H "Authorization: Bearer private_..."

Example Response

json

{
  "data": [
    {
      "id": "clx8a9b0c1d2e3f4g5h6",
      "type": "team",
      "targetId": "clx6t7u8v9w0x1y2z3a4",
      "fte": 0.6,
      "startDate": "2025-01-01",
      "endDate": null,
      "createdAt": "2024-12-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:00:00Z"
    },
    {
      "id": "clx9b0c1d2e3f4g5h6i7",
      "type": "team",
      "targetId": "clx3d4e5f6g7h8i9j0k1",
      "fte": 0.4,
      "startDate": "2025-01-01",
      "endDate": null,
      "createdAt": "2024-12-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "hasNextPage": false
  }
}

Create Employee Assignment

POST /org/:orgId/assignments/employees

Create Request Body

Field	Type	Required	Description
`employeeId`	`string`	Yes	ID of the employee to assign.
`teamId`	`string \| null`	Conditional	Target team ID. Provide either `teamId` or `projectId`, not both.
`projectId`	`string \| null`	Conditional	Target project ID. Provide either `teamId` or `projectId`, not both.
`fte`	`number`	Yes	FTE allocation (0--10). `1.0` = full-time.
`startDate`	`date (YYYY-MM-DD)`	Yes	Assignment start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Assignment end date. `null` = ongoing.
`role`	`string \| null`	No	Role within this assignment (e.g. `"Tech Lead"`, `"IC"`). Distinct from the employee's job role.

Example: Assign Employee to a Team

bash

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "clx1a2b3c4d5e6f7g8h9",
    "teamId": "clx6t7u8v9w0x1y2z3a4",
    "fte": 0.6,
    "startDate": "2026-04-01"
  }'

Example: Assign Employee to a Project

bash

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "clx1a2b3c4d5e6f7g8h9",
    "projectId": "clx7p8r9q0s1t2u3v4w5",
    "fte": 0.5,
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "role": "Tech Lead"
  }'

Example Response

json

{
  "data": {
    "id": "clx2n3o4p5q6r7s8t9u0",
    "type": "project",
    "targetId": "clx7p8r9q0s1t2u3v4w5",
    "fte": 0.5,
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "createdAt": "2026-04-08T10:00:00Z",
    "updatedAt": "2026-04-08T10:00:00Z"
  }
}

Status: 201 Created

Update Employee Assignment

PATCH /org/:orgId/assignments/employees/:id

Update Request Body

Field	Type	Required	Description
`fte`	`number`	No	Updated FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	No	Updated start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Updated end date. Set `null` to make ongoing.
`role`	`string \| null`	No	Updated role within this assignment.

bash

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees/clx8a9b0c1d2e3f4g5h6" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fte": 0.8,
    "endDate": "2026-12-31"
  }'

Delete Employee Assignment

DELETE /org/:orgId/assignments/employees/:id

Status: 204 No Content

Contractor Assignments

Endpoints

Method	Path	Description
`GET`	`/org/:orgId/assignments/contractors`	List contractor assignments
`GET`	`/org/:orgId/assignments/contractors/:id`	Get assignment
`POST`	`/org/:orgId/assignments/contractors`	Create assignment
`PATCH`	`/org/:orgId/assignments/contractors/:id`	Update assignment
`DELETE`	`/org/:orgId/assignments/contractors/:id`	Delete assignment

Create Request Body

Field	Type	Required	Description
`contractorId`	`string`	Yes	ID of the contractor to assign.
`teamId`	`string \| null`	Conditional	Target team ID. Provide either `teamId` or `projectId`.
`projectId`	`string \| null`	Conditional	Target project ID. Provide either `teamId` or `projectId`.
`fte`	`number`	Yes	FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	Yes	Assignment start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Assignment end date. `null` = ongoing.
`role`	`string \| null`	No	Role within this assignment.

Example: Create Contractor Assignment

bash

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/contractors" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contractorId": "clx4c5d6e7f8g9h0i1j2",
    "teamId": "clx6t7u8v9w0x1y2z3a4",
    "fte": 1.0,
    "startDate": "2026-04-01",
    "endDate": "2026-09-30"
  }'

Update Request Body

Field	Type	Required	Description
`fte`	`number`	No	Updated FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	No	Updated start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Updated end date. Set `null` to make ongoing.
`role`	`string \| null`	No	Updated role.

Vacancy Assignments

Endpoints

Method	Path	Description
`GET`	`/org/:orgId/assignments/vacancies`	List vacancy assignments
`GET`	`/org/:orgId/assignments/vacancies/:id`	Get assignment
`POST`	`/org/:orgId/assignments/vacancies`	Create assignment
`PATCH`	`/org/:orgId/assignments/vacancies/:id`	Update assignment
`DELETE`	`/org/:orgId/assignments/vacancies/:id`	Delete assignment

Create Request Body

Field	Type	Required	Description
`vacancyId`	`string`	Yes	ID of the vacancy to assign.
`teamId`	`string \| null`	Conditional	Target team ID. Provide either `teamId` or `projectId`.
`projectId`	`string \| null`	Conditional	Target project ID. Provide either `teamId` or `projectId`.
`fte`	`number`	No	FTE allocation (0--10). Default: `1.0`.
`startDate`	`date (YYYY-MM-DD)`	Yes	Assignment start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Assignment end date. `null` = ongoing.
`role`	`string \| null`	No	Role within this assignment.

Example: Create Vacancy Assignment

bash

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/vacancies" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vacancyId": "clx5v6w7x8y9z0a1b2c3",
    "teamId": "clx6t7u8v9w0x1y2z3a4",
    "fte": 1.0,
    "startDate": "2026-06-01"
  }'

Update Request Body

Field	Type	Required	Description
`fte`	`number`	No	Updated FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	No	Updated start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Updated end date. Set `null` to make ongoing.
`role`	`string \| null`	No	Updated role.

When a vacancy is filled

When you fill a vacancy via POST /vacancies/:id/fill, all vacancy assignments are automatically transferred to the new employee. You do not need to manually recreate them. See Fill a Vacancy.

Team-to-Project Assignments

Endpoints

Method	Path	Description
`GET`	`/org/:orgId/assignments/teams`	List team-project assignments
`GET`	`/org/:orgId/assignments/teams/:id`	Get assignment
`POST`	`/org/:orgId/assignments/teams`	Create assignment
`PATCH`	`/org/:orgId/assignments/teams/:id`	Update assignment
`DELETE`	`/org/:orgId/assignments/teams/:id`	Delete assignment

Team-to-project assignments represent the portion of a team's capacity allocated to a project.

Team Assignment Response Object

Field	Type	Description
`id`	`string`	Unique identifier (CUID format). System-generated. Read-only.
`targetId`	`string`	ID of the target project.
`fte`	`number`	FTE allocation of the team to this project.
`startDate`	`date (YYYY-MM-DD)`	Allocation start date.
`endDate`	`date (YYYY-MM-DD) \| null`	Allocation end date. `null` = ongoing.
`createdAt`	`datetime (ISO 8601)`	Read-only.
`updatedAt`	`datetime (ISO 8601)`	Read-only.

Create Request Body

Field	Type	Required	Description
`teamId`	`string`	Yes	ID of the team to allocate.
`projectId`	`string`	Yes	ID of the project to allocate the team to.
`fte`	`number`	Yes	FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	Yes	Allocation start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Allocation end date. `null` = ongoing.
`role`	`string \| null`	No	Team's role on this project (e.g. `"Primary"`, `"Support"`).
`costCategory`	`string \| null`	No	Cost categorisation for this allocation (e.g. `"CapEx"`, `"OpEx"`).

Update Request Body

Field	Type	Required	Description
`fte`	`number`	No	Updated FTE allocation (0--10).
`startDate`	`date (YYYY-MM-DD)`	No	Updated start date.
`endDate`	`date (YYYY-MM-DD) \| null`	No	Updated end date. Set `null` to make ongoing.
`role`	`string \| null`	No	Updated role.
`costCategory`	`string \| null`	No	Updated cost categorisation.

Example: Create Team-to-Project Assignment

bash

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/teams" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "clx6t7u8v9w0x1y2z3a4",
    "projectId": "clx7p8r9q0s1t2u3v4w5",
    "fte": 0.5,
    "startDate": "2026-01-15",
    "endDate": "2026-09-30",
    "costCategory": "CapEx"
  }'

Example Response

json

{
  "data": {
    "id": "clx1t2p3a4s5g6n7h8i9",
    "targetId": "clx7p8r9q0s1t2u3v4w5",
    "fte": 0.5,
    "startDate": "2026-01-15",
    "endDate": "2026-09-30",
    "createdAt": "2026-04-08T10:00:00Z",
    "updatedAt": "2026-04-08T10:00:00Z"
  }
}

Status: 201 Created

Error Responses

Validation Error (400)

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      { "field": "employeeId", "message": "employeeId is required" },
      { "field": "teamId", "message": "Provide either teamId or projectId, not both" }
    ],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assignment not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Employees -- The people being assigned.
Contractors -- External workers being assigned.
Vacancies -- Planned hires being assigned.
Teams -- Assignment targets and sources.
Projects -- Assignment targets.
Recipes -- Step-by-step guides for common assignment workflows.

Assignments ​

Concepts ​

Assignment Types ​

Request vs. Response Fields ​

FTE (Full-Time Equivalent) ​

Time-Bounded Records ​

Assignment Response Object ​

Employee Assignments ​

Endpoints ​

List Employee Assignments ​

Query Parameters ​

Example Request ​

Example Response ​

Create Employee Assignment ​

Create Request Body ​

Example: Assign Employee to a Team ​

Example: Assign Employee to a Project ​

Example Response ​

Update Employee Assignment ​

Update Request Body ​

Delete Employee Assignment ​

Contractor Assignments ​

Endpoints ​

Create Request Body ​

Example: Create Contractor Assignment ​

Update Request Body ​

Vacancy Assignments ​

Endpoints ​

Create Request Body ​

Example: Create Vacancy Assignment ​

Update Request Body ​

Team-to-Project Assignments ​

Endpoints ​

Team Assignment Response Object ​

Create Request Body ​

Update Request Body ​

Example: Create Team-to-Project Assignment ​

Example Response ​

Error Responses ​

Validation Error (400) ​

Not Found (404) ​

Related Endpoints ​

Assignments

Concepts

Assignment Types

Request vs. Response Fields

FTE (Full-Time Equivalent)

Time-Bounded Records

Assignment Response Object

Employee Assignments

Endpoints

List Employee Assignments

Query Parameters

Example Request

Example Response

Create Employee Assignment

Create Request Body

Example: Assign Employee to a Team

Example: Assign Employee to a Project

Example Response

Update Employee Assignment

Update Request Body

Delete Employee Assignment

Contractor Assignments

Endpoints

Create Request Body

Example: Create Contractor Assignment

Update Request Body

Vacancy Assignments

Endpoints

Create Request Body

Example: Create Vacancy Assignment

Update Request Body

Team-to-Project Assignments

Endpoints

Team Assignment Response Object

Create Request Body

Update Request Body

Example: Create Team-to-Project Assignment

Example Response

Error Responses

Validation Error (400)

Not Found (404)

Related Endpoints