Members and Groups

These routes are the workspace's directory. They tell you the id and type of every person and group in the workspace, which is what every other v3 route takes when it refers to someone: task assignees, comment mentions, saved view filters and the member an API key acts as. They also give you each member's email address, role and whether they are still active, so you can match the workspace's people to your own system's users.

All four routes are reads. Members, roles and groups are managed in the app, on the Team page; see Roles & Permissions for what each role can do. Any key can call these routes, including a key that acts as the workspace.

Members and groups are identified by integer ids, not GUID keys, and an id is only meaningful within its own workspace. Member ids and group ids are drawn from different tables, so member 12 and group 12 are two different assignees — which is why every entry carries a type beside its id.

tip

To get every member, group, tag and template in one unpaged response — for example before writing a template document — use GET /v3/workspace instead.

Endpoints

Method	Path	Description	MCP tool
GET	/v3/members	List members	list_members
GET	/v3/members/{id}	Get a member	get_member
GET	/v3/groups	List groups	list_groups
GET	/v3/groups/{id}	Get a group	get_group

The Member Object

Field	Type	Description
id	integer	The member's id. This is the id that assignees, comment mentions, activity entries and the Tasks grid use, and the id GET /v3/auth/test reports for the member a key acts as.
type	string	Always TeamMember. Send type and id together wherever a route takes an assignee.
name	string	The member's full name. Absent for a member recorded with a surname and no first name — use firstName, lastName or email instead.
firstName	string	The member's first name. Absent when there is none.
lastName	string	The member's surname. Absent when there is none.
email	string	The member's email address — the one value that is unique for every member, and the most reliable way to match a member to a user in another system.
role	string	Administrator, Member or Guest. Absent in the rare case that the stored role is none of these.
isActive	boolean	false for a member who has been deactivated.

{
  "id": 1044,
  "type": "TeamMember",
  "name": "Priya Patel",
  "firstName": "Priya",
  "lastName": "Patel",
  "email": "priya.patel@acme.example",
  "role": "Member",
  "isActive": true
}

Permissions such as Template.Creator are not reported. Every workspace also has an anonymous member that carries work done by keys acting as the workspace; it is not a person and never appears on these routes.

The Group Object

The group list returns this shape. Get a group adds its members.

Field	Type	Description
id	integer	The group's id.
type	string	Always Group.
name	string	The group's name.
members	array of Member	Who is in the group, ordered by name. Only on Get a group.

{
  "id": 12,
  "type": "Group",
  "name": "Finance Team"
}

List Members

Returns the people in the workspace, one page at a time. Guests are included and deactivated members are left out by default — the same set that assignees and mentions are resolved against, so everybody listed can be assigned work.

GET /v3/members

Parameters

Name	In	Type	Required	Description
search	query	string	No	Matches anywhere in the full name, first name, surname or email address, case-insensitively. A search that matches nobody returns an empty list, not a 404.
role	query	string	No	Only members with this role: Administrator, Member or Guest, in any case. Any other value is refused.
includeInactive	query	boolean	No	true to include deactivated members. Default false. Any value other than true or false is refused.
sort	query	string	No	name or email, optionally with :asc or :desc. Default name:asc. Members with the same name are ordered by id.
pageSize	query	integer	No	Results per page, 1–100. Default 50. A value outside that range is treated as 50.
after	query	string	No	The nextCursor from the previous page. Send the same search, role, includeInactive, sort and pageSize with it.

See Pagination for how cursors work.

Example

GET https://api.checkflow.io/v3/members?role=Member&pageSize=2
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "items": [
    {
      "id": 1043,
      "type": "TeamMember",
      "name": "James Okafor",
      "firstName": "James",
      "lastName": "Okafor",
      "email": "james.okafor@acme.example",
      "role": "Member",
      "isActive": true
    },
    {
      "id": 1044,
      "type": "TeamMember",
      "name": "Priya Patel",
      "firstName": "Priya",
      "lastName": "Patel",
      "email": "priya.patel@acme.example",
      "role": "Member",
      "isActive": true
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoibmFtZTphc2MiLCJvIjoyfQ",
  "hasMore": true,
  "total": 5
}

total is the number of members that match the filters.

Responses

Status	Code	When
200	—	The page of members.
400	VALIDATION_ERROR	field is role for an unknown role, includeInactive for a value other than true or false, sort for an unknown sort field or after for a cursor that cannot be read or was issued for a different query.

Notes

• A member with no name sorts after everybody else on name:asc and before everybody else on name:desc.
• Deactivated members are left out by default because they cannot be assigned work. They are still worth looking up with includeInactive=true — they remain the authors of the comments they wrote and the tasks they completed.

Get a Member

Returns one member by id. Use it to turn an id you were handed — on a task's assignees, a comment's mentions or an activity entry — into a name and an email address without reading the whole list.

GET /v3/members/{id}

Parameters

Name	In	Type	Required	Description
id	path	integer	Yes	The member's id. Must be a positive whole number.

Example

GET https://api.checkflow.io/v3/members/1044
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "id": 1044,
  "type": "TeamMember",
  "name": "Priya Patel",
  "firstName": "Priya",
  "lastName": "Patel",
  "email": "priya.patel@acme.example",
  "role": "Member",
  "isActive": true
}

Responses

Status	Code	When
200	—	The Member.
400	VALIDATION_ERROR	field is id: the id is not a positive whole number.
404	NOT_FOUND	No member of this workspace has that id. A member of another workspace answers the same way.

Notes

A deactivated member is returned, with isActive set to false, rather than answered with a 404 — they still appear in the workspace's history.

List Groups

Returns the workspace's groups, one page at a time. A group can be assigned work and mentioned in a comment exactly as a member can, so its id and type go into the same places.

GET /v3/groups

The list does not include each group's members. To see who is in a group, get the group.

Parameters

Name	In	Type	Required	Description
search	query	string	No	Matches anywhere in the group name, case-insensitively. A search that matches nothing returns an empty list, not a 404.
sort	query	string	No	name, optionally with :asc or :desc. Default name:asc. Groups with the same name are ordered by id.
pageSize	query	integer	No	Results per page, 1–100. Default 50. A value outside that range is treated as 50.
after	query	string	No	The nextCursor from the previous page. Send the same search, sort and pageSize with it.

Example

GET https://api.checkflow.io/v3/groups?search=fin
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "items": [
    {
      "id": 12,
      "type": "Group",
      "name": "Finance Team"
    }
  ],
  "hasMore": false,
  "total": 1
}

Responses

Status	Code	When
200	—	The page of groups.
400	VALIDATION_ERROR	field is sort for a sort field other than name; or after for a cursor that cannot be read or was issued for a different query.

Get a Group

Returns one group and the members in it.

GET /v3/groups/{id}

Parameters

Name	In	Type	Required	Description
id	path	integer	Yes	The group's id. Must be a positive whole number.

Example

GET https://api.checkflow.io/v3/groups/12
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "id": 12,
  "type": "Group",
  "name": "Finance Team",
  "members": [
    {
      "id": 1043,
      "type": "TeamMember",
      "name": "James Okafor",
      "firstName": "James",
      "lastName": "Okafor",
      "email": "james.okafor@acme.example",
      "role": "Member",
      "isActive": true
    },
    {
      "id": 1044,
      "type": "TeamMember",
      "name": "Priya Patel",
      "firstName": "Priya",
      "lastName": "Patel",
      "email": "priya.patel@acme.example",
      "role": "Member",
      "isActive": true
    }
  ]
}

Responses

Status	Code	When
200	—	The Group, with members.
400	VALIDATION_ERROR	field is id: the id is not a positive whole number.
404	NOT_FOUND	No group of this workspace has that id. A group of another workspace answers the same way.

Notes

• members lists active members only. A member who is deactivated drops out of the group's list without being removed from the group, which matches how the app treats the group when it is assigned work.
• Assigning a task to a group is not the same as assigning it to each of its members: a group assignment follows the group as people join and leave it.

Related Pages

• Workspace — every member, group, tag and template in one unpaged response.
• Tasks Grid — filter work by TeamMember:<id> or Group:<id> using the ids from these routes.
• Group Management — how groups are created and edited in the app.
• Roles & Permissions — what the Administrator, Member and Guest roles allow.