---
title: "List team members"
method: GET
path: "/public-api/v1/team_members"
tags: ["Team Members"]
---

# List team members

`GET /public-api/v1/team_members`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/team_members`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Lists the people in your Bonsai account, a page at a time. This is where
you turn a name into an id before assigning work: use
`company_member_id` for `assignee_member_id` and `owner_member_id`, and
`user_id` for `filter[assignee_id]` on the tasks list.

Two fields that sound alike mean different things. `role` is a job title
your team typed in, such as `Software Engineer`, and carries no authority.
`permission_profile` is the profile that decides what the member can do,
such as `Owner` or `Collaborator`.

Your clients are not team members and never appear here.

## Membership status

There is no single status field. Work it out from three timestamps,
checking them in this order:

| Condition | Status |
| --- | --- |
| `deactivated_at` is set | Deactivated — no access, whatever else is set |
| `declined_at` is set | Declined the invitation |
| `confirmed_at` is set | Active |
| all three are `null` | Invited, waiting for a response |

## Filtering

- `filter[name]` — searches member names, ignoring case.
- `filter[id]` — one or more team member ids.
- `filter[user_id]` — one or more user ids.
- `filter[project_id]` — one or more project ids. Returns only the
  members assigned to those projects.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[id]` string
- `filter[user_id]` string
- `filter[project_id]` string
- `filter[name]` string

## Response `200`

A page of team members.

- object
  - `data` TeamMember[], required
    - `user_id` integer, nullable, required: Id of the Bonsai user behind the membership, or `null` for an invitation nobody has accepted yet.
    - `deactivated_at` string, date-time, nullable, required: When an administrator deactivated the member, or `null`. A member with a value here has no access, whatever `confirmed_at` says.
    - `confirmed_at` string, date-time, nullable, required: When the member accepted their invitation, or `null` while it is still outstanding.
    - `declined_at` string, date-time, nullable, required: When the member declined their invitation, or `null`. Never set alongside `confirmed_at`.
    - `company_member_id` integer, required: Unique identifier for the membership. This is the value write endpoints accept as `assignee_member_id` or `owner_member_id`.
    - `name` string, nullable, required: The member's full name, or `null` before they accept their invitation.
    - `email` string, nullable, required: The member's email address.
    - `role` string, nullable, required: The member's job title, for example `Software Engineer`. Free text set by your team, `null` when unset. It carries no authorization meaning — see `permission_profile` for that.
    - `permission_profile` string, nullable, required: Name of the permission profile that decides what the member is allowed to do, for example `Owner` or `Collaborator`. `null` when unset.
  - `meta` PaginatedMeta, required: Metadata returned alongside every list response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.
    - `pagination` Pagination, required: Where the returned page sits in the full result set.
      - `page` integer, required: The page that was returned.
      - `page_size` integer, required: How many records this page can hold.
      - `has_more` boolean, required: Whether at least one more page follows this one. Keep incrementing `page[number]` while this is `true`.

## Other responses

- `400`: A filter key is unknown, an id filter is not an integer, or a pagination parameter is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to see your team.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

[API](https://skmtc.dev/hellobonsai/apis/bonsai-api.md) - [All operations](https://skmtc.dev/hellobonsai/apis/bonsai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hellobonsai/apis/bonsai-api/revisions/abf12ed6a8d3?raw)