# Retrieve a list of members

`GET /api/search/members-basic/{searchText}`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Retrieve a list of members](https://support.gladstonesoftware.cloud/reference/configuration/retrieve-a-list-of-members)

## Overview

Finds members by id, by name, or by the company they work for, and returns enough of each to
populate a picker: name, site, contact details, price level and account status.

How the search behaves depends entirely on what `searchText` looks like:

- **All digits** — treated as a member id and matched exactly. Nothing else is searched, so `12345`
  never matches a member called "12345 Ltd".
- **One term** — matched as a substring of the member's surname **or** of their company name.
- **Two terms separated by a comma** (`Smith,John`) — the first is matched as a substring of the
  surname and the second as a substring of the forenames, and both must match. Company is not
  searched in this form.

Matching is partial and case-insensitive; there is no scoring or fuzzy matching, so a misspelling
returns nothing.

**Results are capped at 100 and there is no paging.** The cap is applied after sorting by surname
then forename, so a broad search silently returns the first hundred alphabetically with no
indication that more exist. Narrow the search rather than trying to page it.

By default only members who have an invoicing account are returned — set `accountRequired=false` to
see the rest. No match returns `200` with an empty array.

## Endpoint

`GET {base_url}/api/search/members-basic/{searchText}`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `searchText` | string | Yes | What to search for: a member id, a surname, a `Surname,Forename` pair, or part of a company name. Trimmed before use, maximum 255 characters — longer fails with `400` and `Search Text cannot be more than 255 characters`. A value that parses as an integer is treated as a member id, and must be greater than zero or the call fails with `MemberId must be a valid integer greater than 0`. More than one comma fails with `When searching by name, please provide either a Last Name, or a Last Name and First Name separated by a comma`, and a leading comma with `When searching by name, Last Name cannot be empty`. The value is used as a SQL `LIKE` pattern without escaping, so `%` and `_` inside it behave as wildcards. |

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `accountRequired` | boolean | No | Whether to return only members who have an invoicing account. **Defaults to `true`**, so by default members without one are invisible to this search — which is the usual explanation for a member you can see elsewhere not appearing here. Set it to `false` to search all members. It filters, it does not sort, and it does not change any field in the response. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/search/members-basic/{searchText}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | integer (int32) | The member's identifier — the value other member endpoints take as `memberId`, and the value this endpoint matches on when `searchText` is numeric. |
| `[].siteId` | string | The site the member belongs to, as a site code rather than a name. Results are not filtered by site, so a search across a multi-site tenant returns members from all of them. |
| `[].firstName` | string | The member's forenames — the whole field, which may contain more than one name. This is what the part after the comma in `searchText` is matched against. Results are sorted by `lastName` then this. |
| `[].lastName` | string | The member's surname, and the primary sort key. This is what a single-term `searchText` is matched against, alongside `company`. |
| `[].telephoneNumber` | string | The member's preferred contact number, chosen for you from the numbers held against them according to which one they nominated as their main one — work, mobile, or home as the fallback. It duplicates one of the stored numbers rather than being a separate field, and it is `null` when that particular number is blank. |
| `[].homeEmail` | string | The member's personal email address. Not searched by this endpoint, and not guaranteed unique or present. |
| `[].workEmail` | string | The member's work email address, held separately from `homeEmail`. Often `null` for consumer members. |
| `[].priceLevel` | string | The member's price level as its code, not its description — the band that determines what they are charged, such as an adult or concession rate. Resolve the code against your price level configuration if you need a label to display. |
| `[].status` | object | The member's account status, with the colours the back office uses to display it. Always present, because the search joins to the status record — a member with no valid status does not appear in results at all. |
| `[].status.id` | string | The status code, for example the value your integration should branch on. Stable across tenants' renaming of the description. |
| `[].status.name` | string | The status's description as configured in the back office — free text, so do not compare against it; use `status.id`. |
| `[].status.textColour` | string | The foreground colour the back office shows this status in, converted from the back office's legacy colour format to a `#RRGGBB` hex string. An **empty string** rather than `null` when no colour is configured. |
| `[].status.backgroundColour` | string | The background colour for the status, in the same `#RRGGBB` form and likewise an empty string when unset. Pair it with `textColour` if you are mirroring the back office's colour coding; there is no guarantee the two contrast. |
| `[].status.bookable` | boolean | False when the member's status is configured as restricted from creating bookings; true otherwise. |
| `[].company` | string | The member's employer as recorded against them. This is the second field a single-term search matches on, which is why a name search can return people whose surname does not match at all. `null` for members with no company recorded. |

## Sample response

```json title="200 OK"
[
  {
    "id": 12345,
    "siteId": "string",
    "firstName": "string",
    "lastName": "string",
    "telephoneNumber": "string",
    "homeEmail": "member@example.com",
    "workEmail": "member@example.com",
    "priceLevel": "string",
    "status": {
      "id": "string",
      "name": "string",
      "textColour": "string",
      "backgroundColour": "string",
      "bookable": true
    },
    "company": "string"
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `searchText` failed validation, with the reason as a plain string body: `Search Text cannot be empty`, `Search Text cannot be more than 255 characters`, `MemberId must be a valid integer greater than 0`, `When searching by name, please provide either a Last Name, or a Last Name and First Name separated by a comma`, or `When searching by name, Last Name cannot be empty`. |
| `500` | Internal server error | An unexpected server-side failure during the search, with an empty body. |