Teams

A team is a group that employees, contractors and vacancies are assigned to. Teams form a single-parent hierarchy through parentTeamId. In the app, teams are archived on a date rather than deleted. See Archive or delete a team.

• IDs. Paths take a Flowstate ID or your externalId. A value of 24–25 lowercase letters and digits that starts with a letter is read as a Flowstate ID. Anything else is read as an externalId.
• Dates. Dates come back as ISO 8601 date-times, e.g. 2026-10-01T00:00:00.000Z.
• Scenarios. Live data only. See Scenarios.

The team object

Endpoints

Sub-resource: custom attribute values at /teams/:id/custom-attributes. Team-to-project time is in Assignments.

List teams

GET /api/v1/org/:orgId/teams

Permission: View Teams (team_teams_view).

Returns archived teams too. To leave them out, skip any team whose archivedAt is on or before today.

Query parameters

Example request

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

Example response

{
  "data": [
    {
      "id": "cmf2k8x1q0021ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "name": "Engineering",
      "externalId": "T-100",
      "teamType": "department",
      "description": null,
      "parentTeamId": null,
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2024-01-05T08:00:00.000Z",
      "metadata": {},
      "createdAt": "2024-01-05T08:00:00.000Z",
      "updatedAt": "2025-09-01T10:00:00.000Z",
      "managerUserId": "cmf2k8x1q0080ab2cd3ef4gh5",
      "archivedAt": null,
      "archiveAppliedAt": null
    },
    {
      "id": "cmf2k8x1q0020ab2cd3ef4gh5",
      "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
      "name": "Platform Engineering",
      "externalId": "T-110",
      "teamType": "engineering",
      "description": "Infrastructure and developer tooling.",
      "parentTeamId": "cmf2k8x1q0021ab2cd3ef4gh5",
      "sourceSystem": "api",
      "sourceSystemId": null,
      "lastSyncedAt": "2024-01-10T08:00:00.000Z",
      "metadata": {},
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2026-08-20T14:00:00.000Z",
      "managerUserId": null,
      "archivedAt": "2026-10-01T00:00:00.000Z",
      "archiveAppliedAt": null
    }
  ],
  "meta": { "page": 1, "limit": 100, "total": 2, "hasNextPage": false }
}

Errors

Retrieve a team

GET /api/v1/org/:orgId/teams/:id

Permission: View Teams (team_teams_view).

The response is the team object with customAttributes. No include parameter.

Example request

curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/T-110" \
  -H "Authorization: Bearer private_..."

Errors

Create a team

POST /api/v1/org/:orgId/teams

Permission: Create Teams (team_teams_create).

Body parameters

Example request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Platform",
    "externalId": "T-120",
    "teamType": "engineering",
    "parentTeamId": "T-100"
  }'

Example response

201 Created.

{
  "data": {
    "id": "cmf2k8x1q0022ab2cd3ef4gh5",
    "organizationId": "cmf2k8x1q0000ab2cd3ef4gh5",
    "name": "Data Platform",
    "externalId": "T-120",
    "teamType": "engineering",
    "description": null,
    "parentTeamId": "cmf2k8x1q0021ab2cd3ef4gh5",
    "sourceSystem": "api",
    "sourceSystemId": null,
    "lastSyncedAt": "2026-09-14T09:00:00.000Z",
    "metadata": {},
    "createdAt": "2026-09-14T09:00:00.000Z",
    "updatedAt": "2026-09-14T09:00:00.000Z",
    "managerUserId": null,
    "archivedAt": null,
    "archiveAppliedAt": null
  }
}

Errors

Update a team

PATCH /api/v1/org/:orgId/teams/:id

Permission: Update Teams (team_teams_update).

Takes the create body with every field optional. null clears a nullable field: "parentTeamId": null makes the team top level. archivedAt and archiveAppliedAt are ignored if sent. The response is the updated team, 200 OK.

Example request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/T-120" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "parentTeamId": "T-110" }'

Errors

As for Create a team, plus 404 NOT_FOUND when no team has that ID or externalId.

Delete a team

DELETE /api/v1/org/:orgId/teams/:id

Permission: Delete Teams (team_teams_delete).

Permanent. The following are deleted with the team, not ended:

• every employee, contractor and vacancy assignment to the team
• the team’s project assignments

Its child teams become top level. A team that a budget refers to can’t be deleted.

Example response

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

Errors

Tasks

Archive or delete a team

Archive a team to retire it. Keep DELETE for teams created in error. Archiving isn’t available over REST.

Read the whole hierarchy

Page through GET /teams?limit=100 until hasNextPage is false. Then build the tree from parentTeamId, where null marks a root.

Related

• Assignments · Employees · Custom attributes · Errors
• Webhooks: writes send team events. See Webhooks.