Assignments

An assignment allocates capacity for a date range: an employee, contractor or vacancy to a team or a project, or a team to a project. Assignments are what the forecast is built from.

All paths are under https://{tenant}.flowstate.inc/api/v1. Assignments are live data; scenarioId is ignored.

Each resource has the same four endpoints:

There’s no endpoint to retrieve one assignment. :id is the assignment’s Flowstate id.

FTE and dates

• fte is the share of a full-time person: 1 is full time, 0.5 half time. Each assignment takes 0 to 10. A person’s assignments can add up to more than 1; Flowstate shows that as over-allocated.
• startDate and endDate are inclusive. endDate: null means ongoing.
• Requests take YYYY-MM-DD or ISO 8601. Responses return ISO 8601 date-times, e.g. "2026-04-01T00:00:00.000Z".

The assignment object

Employee, contractor and vacancy assignments:

List responses also carry targetId (the team or project id) and employeeId / contractorId / vacancyId on each item.

Team assignments:

Responses can carry further fields that aren’t listed here. Don’t depend on them.

List assignments

GET /org/:orgId/assignments/{resource}

Returns every assignment of that resource in the organisation. There are no filters; filter on targetId and the person id client-side.

For employees, contractors and vacancies, a page holds up to limit team assignments followed by up to limit project assignments, and meta.total counts both. Keep requesting pages while meta.hasNextPage is true.

curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees?limit=100" \
  -H "Authorization: Bearer private_..."

{
  "data": [
    {
      "id": "clx8a9b0c1d2e3f4g5h6i7j8k",
      "type": "team",
      "liveEmployeeId": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "liveTeamId": "clx6t7u8v9w0x1y2z3a4b5c6d",
      "employeeId": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "targetId": "clx6t7u8v9w0x1y2z3a4b5c6d",
      "fte": 1,
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": null,
      "role": null,
      "createdAt": "2024-12-15T10:00:00.000Z",
      "updatedAt": "2025-06-01T14:00:00.000Z"
    },
    {
      "id": "clx2n3o4p5q6r7s8t9u0v1w2x",
      "type": "project",
      "liveEmployeeId": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "liveProjectId": "clx7p8r9q0s1t2u3v4w5x6y7z",
      "employeeId": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "targetId": "clx7p8r9q0s1t2u3v4w5x6y7z",
      "fte": 0.5,
      "startDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-09-30T00:00:00.000Z",
      "role": "Tech Lead",
      "createdAt": "2026-03-20T09:12:00.000Z",
      "updatedAt": "2026-03-20T09:12:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 100, "total": 2, "hasNextPage": false }
}

Create an assignment

POST /org/:orgId/assignments/{resource}

Employee, contractor and vacancy assignments:

Send exactly one of teamId and projectId.

Team assignments:

201 Created with the assignment object.

Update an assignment

PATCH /org/:orgId/assignments/{resource}/:id

The person, team and project can’t be changed. To move an allocation, end it and create a new one.

200 OK with the updated assignment.

Delete an assignment

DELETE /org/:orgId/assignments/{resource}/:id

{ "data": { "id": "clx2n3o4p5q6r7s8t9u0v1w2x", "deleted": true } }

Deleting removes the allocation from history too. To stop an allocation but keep the record, set endDate.

Allocate someone to a project for a date range

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

{
  "data": {
    "id": "clx2n3o4p5q6r7s8t9u0v1w2x",
    "type": "project",
    "liveEmployeeId": "clx1a2b3c4d5e6f7g8h9i0j1k",
    "liveProjectId": "clx7p8r9q0s1t2u3v4w5x6y7z",
    "fte": 0.5,
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-09-30T00:00:00.000Z",
    "role": "Tech Lead",
    "createdAt": "2026-03-20T09:12:00.000Z",
    "updatedAt": "2026-03-20T09:12:00.000Z"
  }
}

Move someone to another team from a date

End the current team assignment the day before, then create the new one.

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees/clx8a9b0c1d2e3f4g5h6i7j8k" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "endDate": "2026-06-30" }'

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/assignments/employees" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "employeeId": "HR-10442", "teamId": "TEAM-PAY", "fte": 1, "startDate": "2026-07-01" }'

Vacancies that get filled

Filling a vacancy ends the vacancy’s open assignments (those with no endDate) the day before the start date, and creates matching assignments for the new employee or contractor from that date. You don’t recreate them.

Errors

See Errors for the error body.

Related

• Projects, Teams, Employees, Contractors, Vacancies