Appearance

Assignments ​

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

Concepts ​

Assignment Types ​

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

Sub-resourceFromToDescription
/assignments/employeesEmployeeTeam or ProjectEmployee allocation
/assignments/contractorsContractorTeam or ProjectContractor allocation
/assignments/vacanciesVacancyTeam or ProjectVacancy allocation
/assignments/teamsTeamProjectTeam-to-project allocation

The type Field ​

Each assignment has a type field that indicates the target:

  • "team" — The resource is assigned to a team
  • "project" — The resource is assigned to a project

The targetId field contains the ID of the team or project.

INFO

Team-to-project assignments (/assignments/teams) always have type: "project" since they exclusively map teams to projects.

FTE (Full-Time Equivalent) ​

The fte field is a decimal between 0 and 1 representing the portion 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 should not exceed 1.0.

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.

Employee Assignments ​

Endpoints ​

MethodPathDescription
GET/org/:orgId/assignments/employeesList employee assignments
GET/org/:orgId/assignments/employees/:idGet assignment
POST/org/:orgId/assignments/employeesCreate assignment
PATCH/org/:orgId/assignments/employees/:idUpdate assignment
DELETE/org/:orgId/assignments/employees/:idDelete assignment

List Employee Assignments ​

GET /org/:orgId/assignments/employees

Query Parameters ​

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger20Records per page (max 200)
employeeIdstring—Filter by employee ID
targetIdstring—Filter by target team or project ID
typestring—Filter by type: "team" or "project"
sortBystringstartDateSort field
sortDirstringascasc or desc
scenarioIdstring—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": "clx8a9b0c1d2e3f4",
      "employeeId": "clx1a2b3c4d5e6f7g8h9",
      "type": "team",
      "targetId": "clx6t7u8v9w0x1y2",
      "fte": 0.6,
      "startDate": "2025-01-01",
      "endDate": null,
      "metadata": {},
      "createdAt": "2024-12-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:00:00Z"
    },
    {
      "id": "clx9b0c1d2e3f4g5",
      "employeeId": "clx1a2b3c4d5e6f7g8h9",
      "type": "team",
      "targetId": "clx3d4e5f6g7h8i9",
      "fte": 0.4,
      "startDate": "2025-01-01",
      "endDate": null,
      "metadata": {},
      "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
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",
    "type": "project",
    "targetId": "clx7p8r9q0s1t2u3",
    "fte": 0.5,
    "startDate": "2026-04-01",
    "endDate": "2026-09-30"
  }'

Status: 201 Created

Update Employee Assignment ​

PATCH /org/:orgId/assignments/employees/:id
bash
curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees/clx8a9b0c1d2e3f4" \
  -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 ​

MethodPathDescription
GET/org/:orgId/assignments/contractorsList contractor assignments
GET/org/:orgId/assignments/contractors/:idGet assignment
POST/org/:orgId/assignments/contractorsCreate assignment
PATCH/org/:orgId/assignments/contractors/:idUpdate assignment
DELETE/org/:orgId/assignments/contractors/:idDelete 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": "clx4c5d6e7f8g9h0",
    "type": "team",
    "targetId": "clx6t7u8v9w0x1y2",
    "fte": 1.0,
    "startDate": "2026-04-01",
    "endDate": "2026-09-30"
  }'

Vacancy Assignments ​

Endpoints ​

MethodPathDescription
GET/org/:orgId/assignments/vacanciesList vacancy assignments
GET/org/:orgId/assignments/vacancies/:idGet assignment
POST/org/:orgId/assignments/vacanciesCreate assignment
PATCH/org/:orgId/assignments/vacancies/:idUpdate assignment
DELETE/org/:orgId/assignments/vacancies/:idDelete 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": "clx5v6w7x8y9z0a1",
    "type": "team",
    "targetId": "clx6t7u8v9w0x1y2",
    "fte": 1.0,
    "startDate": "2026-06-01"
  }'

Team-to-Project Assignments ​

Endpoints ​

MethodPathDescription
GET/org/:orgId/assignments/teamsList team-project assignments
GET/org/:orgId/assignments/teams/:idGet assignment
POST/org/:orgId/assignments/teamsCreate assignment
PATCH/org/:orgId/assignments/teams/:idUpdate assignment
DELETE/org/:orgId/assignments/teams/:idDelete assignment

Team-to-project assignments represent the portion of a team's capacity allocated to a project. The type is always "project".

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": "clx6t7u8v9w0x1y2",
    "targetId": "clx7p8r9q0s1t2u3",
    "fte": 0.5,
    "startDate": "2026-01-15",
    "endDate": "2026-09-30"
  }'

Example Response ​

json
{
  "data": {
    "id": "clx1t2p3a4s5g6n7",
    "teamId": "clx6t7u8v9w0x1y2",
    "type": "project",
    "targetId": "clx7p8r9q0s1t2u3",
    "fte": 0.5,
    "startDate": "2026-01-15",
    "endDate": "2026-09-30",
    "metadata": {},
    "createdAt": "2026-03-11T10:00:00Z",
    "updatedAt": "2026-03-11T10:00:00Z"
  }
}

Field Reference ​

Employee / Contractor / Vacancy Assignments ​

FieldTypeRequiredDescription
idstring—Unique identifier (read-only)
employeeIdstringYes *ID of the employee (* employee assignments only)
contractorIdstringYes *ID of the contractor (* contractor assignments)
vacancyIdstringYes *ID of the vacancy (* vacancy assignments)
typestringYes"team" or "project"
targetIdstringYesID of the target team or project
ftenumberYesFTE allocation (0 to 1)
startDatedateYesAssignment start date (ISO 8601)
endDatedateNoAssignment end date (null = ongoing)
metadataobjectNoArbitrary JSON metadata (default: {})
createdAtdatetime—Record creation timestamp (read-only)
updatedAtdatetime—Last modification timestamp (read-only)

Team-to-Project Assignments ​

FieldTypeRequiredDescription
idstring—Unique identifier (read-only)
teamIdstringYesID of the team
typestring—Always "project" (read-only)
targetIdstringYesID of the target project
ftenumberYesFTE allocation (0 to 1)
startDatedateYesAssignment start date (ISO 8601)
endDatedateNoAssignment end date (null = ongoing)
metadataobjectNoArbitrary JSON metadata (default: {})
createdAtdatetime—Record creation timestamp (read-only)
updatedAtdatetime—Last modification timestamp (read-only)

Flowstate Documentation

Copyright 2024-2026 Flowstate Inc.