---
title: "Search members"
method: POST
path: "/members/search"
tags: ["members"]
---

# Search members

`POST /members/search`

## Purpose
Performs a filtered search over members using a POST request body.
Supports batch lookups by IDs or emails, plus all filters from GET /v2/members.

Uses `filter`, `search`, and `return` objects under `data`.

## Key Features
- `filter.id`: Filter by member UUIDs (OR logic, max 100)
- `filter.fields.email`: Filter by email addresses (OR logic, max 100, requires `members_pii:read` scope)
- `filter.fields.role`: Filter by roles (OR logic)
- `filter.fields.disabled`: Exclusive filter for disabled members (true = only disabled)
- `filter.fields.invitationPending`: Exclusive filter for pending members (true = only pending)
- `search.query`: Full-text search on name or email (requires `members_pii:read` scope)
- `return.includeDisabled`: Include disabled members alongside active
- `return.includeInvitationPending`: Include pending members alongside accepted

## Filter Logic
- Multiple values within a filter use **OR** logic (e.g., `filter.id` with two UUIDs)
- Different filters use **AND** logic (e.g., `filter.fields.email` AND `filter.fields.role`)
- Disabled and invited members are excluded by default
- Use `filter.fields.disabled: true` to get **only** disabled members
- Use `return.includeDisabled: true` to include disabled **alongside** active members
- If both `filter.fields.disabled` and `return.includeDisabled` are set, the filter takes precedence

## Important Notes
- The `filter.id` and `filter.fields.email` filters accept at most 100 items each; exceeding this returns a 400 error
- Filtering by email or query requires the `members_pii:read` scope; requests without it return a 400 error
- Unknown keys in `filter.fields` return a 400 error
- Pagination uses cursor-based navigation via `pageCursor` query parameter

## Query parameters

- `pageCursor` string

## Request body

- MemberSearchRequest
  - `data` MemberSearchData — Search data using structured `filter`, `search`, and `return` objects.
    - `filter` MemberSearchFilter — Structured filters for member search. Different filter groups use AND logic. All filters are optional.
      - `id` union — Filter by member UUIDs (OR logic).
        - string, uuid — A universally unique identifier (UUID).
        - UUID[]
      - `fields` MemberSearchFilterFields — Field-level filters. Multiple values within a field use OR logic. Email matching is case-insensitive. Unknown fields return a 400 error.
        - `email` union — Filter by email address. Single string or array (OR logic), case-insensitive. Requires `members_pii:read` scope.
          - string, email
          - string[]
        - `role` union — Filter by role. Single string or array (OR logic).
          - 'admin' | 'maker' | 'viewer' | 'contributor'
          - string[]
        - `disabled` boolean — Exclusive filter for disabled members. When `true`, returns **only** disabled members. When absent, disabled members are excluded by default. Use `return.includeDisabled` instead if you want disabled members alongside active ones.
        - `invitationPending` boolean — Exclusive filter for members with pending invitations. When `true`, returns **only** pending members. When absent, pending members are excluded by default. Use `return.includeInvitationPending` instead if you want pending members alongside accepted ones.
    - `search` MemberSearchSearch — Full-text search options. Combined with filters using AND logic.
      - `query` string — Full-text search query. Performs case-insensitive partial match on member name or email. Requires `members_pii:read` scope.
    - `return` MemberSearchReturn — Controls inclusion of normally-excluded members in the response.
      - `includeDisabled` boolean — Include disabled members alongside active members. Default false. If `filter.fields.disabled` is also set, the filter takes precedence.
      - `includeInvitationPending` boolean — Include members with pending invitations alongside accepted members. Default false. If `filter.fields.invitationPending` is also set, the filter takes precedence.

## Response `200`

A paginated list of members

- object
  - `data` Member[]
    - `id` string, uuid, required — Unique identifier of the member
    - `type` 'member', required — Resource type identifier
    - `fields` MemberFields, required — Fields of a member resource. Note: When the `members:pii:read` scope is not present, the `name`, `username` and `email` fields will return `[redacted]` instead of actual values.
      - `name` union, required
        - string — Display name of the member.
        - '[redacted]' — The value `[redacted]`. Used to hide personally identifiable information in cases the request doesn't have the required `members:pii:read` OAuth2 scope.
      - `username` union, required
        - string — Username of the member.
        - '[redacted]' — The value `[redacted]`. Used to hide personally identifiable information in cases the request doesn't have the required `members:pii:read` OAuth2 scope.
      - `email` union, required
        - string — The email of a Productboard user that has access to your workspace.
        - '[redacted]' — The value `[redacted]`. Used to hide personally identifiable information in cases the request doesn't have the required `members:pii:read` OAuth2 scope.
      - `role` 'admin' | 'maker' | 'viewer' | 'contributor', required — Role of the member in the workspace.
      - `disabled` boolean, required — Whether the member is disabled.
      - `invitationPending` boolean, required — Whether the member has a pending invitation that has not yet been accepted.
      - `teams` TeamReference[] — List of teams the member belongs to. Always included in the response.
        - `id` string, uuid, required — Unique identifier of the team
        - `type` 'team', required — Resource type identifier
        - `links` TeamLinks, required — Links for navigating team resources.
          - `self` string, uri, required — URL of the team resource.
          - `members` string, uri, required — URL of the paginated team members sub-resource.
          - `html` string, uri, required — URL of the team page in the Productboard UI.
    - `links` MemberLinks, required — Links for navigating member resources.
      - `self` string, uri, required — URL of the member resource.
      - `html` string, uri, required — URL of the member page in the Productboard UI.
  - `links` ListLinks
    - `next` string, nullable, required

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)