---
title: "Search fans to add as a team member (admin)"
method: GET
path: "/api/admin/teams/{teamId}/members/candidates"
tags: ["Admin", "Teams"]
---

# Search fans to add as a team member (admin)

`GET /api/admin/teams/{teamId}/members/candidates`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/admin/teams/{teamId}/members/candidates`
- Auth: HTTP bearer

Gate: canManageTeam with owner or legacy admin on the team, or platform admin/superadmin (the same set as Add team member). Editors, viewers and outsiders get 403; anonymous 401. `q` is trimmed, 2-50 chars, matched case-insensitively against handle and name only (never email), with `%` and `_` literal. `limit` is an integer 1-10, default 5; out-of-range values are 400 VALIDATION_ERROR, not clamped. Fans who already hold a TeamAdmin row on the team are excluded. Ordered by handle ascending, unpaged. Each row is { id, handle, name, profileUrl }; email is never returned. Limited to 30 requests per 60s per caller once the gate passes (429 RATE_LIMITED); a limiter outage fails closed (503 RATE_LIMITER_UNAVAILABLE). Every response is `Cache-Control: private, no-store`.

## Path parameters

- `teamId` string, required

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

{ success, data: FanCandidate[] }

- object
  - `success` boolean
  - `data` object[]
    - `id` string, required
    - `handle` string, nullable, required
    - `name` string, nullable, required
    - `profileUrl` string, required

## Other responses

- `400`: { success: false, error, code: VALIDATION_ERROR }
- `401`: { success: false, error, code: UNAUTHORIZED }
- `403`: { success: false, error, code: FORBIDDEN }
- `429`: { success: false, error, code: RATE_LIMITED }
- `500`: { success: false, error, code: INTERNAL_ERROR }
- `503`: { success: false, error, code: RATE_LIMITER_UNAVAILABLE }

## Changes

- **2026-11-18** `6de639c52609`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/admin/teams/:teamId/members/candidates/get.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
