> This page is for version v4 (default).
> For other versions, use one of these documentation indexes:
> - v4 (default): https://help.getzep.com/v4/llms.txt
> - v3: https://help.getzep.com/v3/llms.txt
> - v2: https://help.getzep.com/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server.

# List member candidates

POST https://api.getzep.com/api/v4/user-groups/{group_uuid}/member-candidates/list
Content-Type: application/json

Requires attribute-based access control to be enabled for your account.

Reference: https://help.getzep.com/sdk-reference/user-groups/members/list-member-candidates

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key  `) — Type "Api-Key" followed by a space and the project API key.

## Request

### Path parameters

- `group_uuid` (string, required) — User group UUID

### Query parameters

- `page_size` (integer, optional, default: 50) — The maximum number of items in one page. The SDK method returns a pager. In Python, `.items` holds only the first page. In TypeScript, `.data` holds only the first page. To read every page, iterate the pager: use `for` or `list(...)` in Python, or `for await` in TypeScript. In Go, the method returns one page, and `Iterator()` reads all pages.
- `cursor` (string, optional) — Opaque page cursor

### Body (application/json)

This endpoint expects a v4.SearchListRequest.

- `search` (string, optional) — Filters results to items matching this free-text search term.

## Response

### 200

OK

- `items` (list of v4.User, optional) — The users on this page.
- `next_cursor` (string, optional) — The cursor to pass as the next request's cursor to fetch the following page; absent when no further pages remain.
- `total_size` (integer, optional) — The total number of matching users, counted at the time of this response. It does not indicate whether more pages remain.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (v4.ErrorBody, optional)

### 401 Unauthorized Error

Unauthorized

- `error` (v4.ErrorBody, optional)

### 403 Forbidden Error

Forbidden

- `error` (v4.ErrorBody, optional)

### 404 Not Found Error

Not Found

- `error` (v4.ErrorBody, optional)

### 409 Conflict Error

Conflict

- `error` (v4.ErrorBody, optional)

## Types

### v4.User

- `created_at` (string, optional) — The time the user was created.
- `disable_default_ontology` (boolean, optional) — When true, disables the use of the default fallback ontology for the user's graph.
- `email` (string, optional) — The email address of the user.
- `first_name` (string, optional) — The first name of the user.
- `graph_uuid` (string, optional) — The unique identifier of the user's graph, populated when the user is created.
- `last_name` (string, optional) — The last name of the user.
- `metadata` (map from string to any, optional) — Arbitrary key-value metadata attached to the user.
- `time_zone` (string, optional) — The user's IANA time zone, used to localize dates in generated context.
- `user_id` (string, optional) — An optional external identity identifier, such as an identity-provider subject claim. Zep uses it to match an identity-provider sign-in to this user. It is not an address; use uuid to address the user in v4. It is unique within the project, can contain at most 500 characters, and cannot be changed after creation. v4 sets it on create; v3 users keep their existing value.
- `uuid` (string, optional) — The unique identifier of the user.

### v4.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "items": [
    {
      "created_at": "string",
      "disable_default_ontology": true,
      "email": "string",
      "first_name": "string",
      "graph_uuid": "string",
      "last_name": "string",
      "metadata": {},
      "time_zone": "string",
      "user_id": "string",
      "uuid": "string"
    }
  ],
  "next_cursor": "string",
  "total_size": 1
}
```