Teams

Manage organizational teams and their hierarchy. Teams represent groups of employees and contractors who work together, and they can be arranged in a tree structure with parent-child relationships.

Team Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
externalId	string | null	Your external identifier for this team. Unique within your organization. Use for lookups via path parameters.
name	string	Team display name (e.g. "Platform Engineering").
teamType	string | null	Classification of the team (e.g. "engineering", "product", "design", "department"). Free-form text.
description	string | null	What this team does and its responsibilities.
parentTeamId	string | null	ID of the parent team for hierarchical org structures. null = top-level team. References another Team.
managerUserId	string | null	ID of the Flowstate user who manages this team.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.
customAttributes	array	Custom attribute values for this team. Returned on GET-by-ID. See Custom Attributes.

---

Endpoints

Method	Path	Description
GET	/org/:orgId/teams	List teams
GET	/org/:orgId/teams/:id	Get team
POST	/org/:orgId/teams	Create team
PATCH	/org/:orgId/teams/:id	Update team
DELETE	/org/:orgId/teams/:id	Delete team

External ID Support

The :id path parameter accepts either a Flowstate CUID (e.g. clx1a2b3c4d5e6f7g8h9) or your externalId. The format is auto-detected.

---

List Teams

GET /org/:orgId/teams

Returns a paginated list of teams in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Free-text search by name or description.
sortBy	string	name	Field to sort by.
sortDir	string	asc	Sort direction: asc or desc.
scenarioId	string	--	Scenario ID for what-if queries.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams?sortBy=name&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx1e2n3g4r5o0t6u7v8",
      "externalId": null,
      "name": "Engineering",
      "teamType": "department",
      "description": "All engineering teams.",
      "parentTeamId": null,
      "managerUserId": "clx9u1s2e3r4t5y6",
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    },
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "externalId": null,
      "name": "Platform Engineering",
      "teamType": "engineering",
      "description": "Core infrastructure and developer tools team.",
      "parentTeamId": "clx1e2n3g4r5o0t6u7v8",
      "managerUserId": null,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 18,
    "hasNextPage": false
  }
}

---

Get Team

GET /org/:orgId/teams/:id

Returns a single team by ID.

Example Request

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

---

Create Team

POST /org/:orgId/teams

Create Request Body

Field	Type	Required	Description
name	string	Yes	Team name.
externalId	string | null	No	Your external identifier. Must be unique within the organization. Cannot resemble a CUID format. Max 255 characters.
teamType	string | null	No	Team classification (e.g. "engineering", "product").
description	string | null	No	Team description.
parentTeamId	string | null	No	Parent team ID. null = top-level team.
managerUserId	string | null	No	Flowstate user ID of the team manager.

Update Request Body

All fields from Create are accepted, all optional. You can set or update the externalId field.

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",
    "teamType": "engineering",
    "description": "Data infrastructure and analytics pipelines.",
    "parentTeamId": "clx1e2n3g4r5o0t6u7v8"
  }'

Status: 201 Created

---

Update Team

PATCH /org/:orgId/teams/:id

Updates one or more fields. Only include the fields you want to change. Set parentTeamId to null to make a team top-level.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/clx6t7u8v9w0x1y2z3a4" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform & Infrastructure",
    "description": "Core infrastructure, developer tools, and cloud platform."
  }'

---

Delete Team

DELETE /org/:orgId/teams/:id

Deletes a team. Teams with active employee or contractor allocations cannot be deleted until those allocations are removed or reassigned.

Status: 204 No Content

---

Team Hierarchy

Teams support a single-parent hierarchy through the parentTeamId field. A team with parentTeamId: null is a top-level team. You can build the full tree client-side by following parentTeamId references.

Example hierarchy:

Engineering (parentTeamId: null)
  +-- Platform Engineering (parentTeamId: "clx1e2n3g4r5o0t6u7v8")
  +-- Product Engineering (parentTeamId: "clx1e2n3g4r5o0t6u7v8")
  |   +-- Payments Team
  |   +-- Growth Team
  +-- Data Platform (parentTeamId: "clx1e2n3g4r5o0t6u7v8")

---

External IDs

You can assign your own externalId during creation or update. This allows you to reference teams by your system's identifier instead of the Flowstate CUID.

• Setting: Pass externalId in the POST or PATCH request body.
• Lookups: Use the external ID directly in path parameters (e.g. GET /teams/MY-EXT-ID).
• Uniqueness: External IDs must be unique per entity type within your organization.
• Format restriction: External IDs cannot match the CUID format (25 lowercase alphanumeric characters starting with a letter).

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      { "field": "name", "message": "name is required" }
    ],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

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

---

Related Endpoints

• Assignments -- Assign employees, contractors, and vacancies to teams.
• Projects -- Projects that teams can be allocated to.
• Employees -- People who belong to teams via assignments.
• Custom Attributes -- Manage custom fields on teams.