# List Members
> Source: /api-reference/partner/members/list
> Search and list members scoped to your organization
> Endpoint: GET /partner/members
> Status: PREVIEW
> Note: Preview. GET /v1/partner/members is live and authoritative for tier, but the response is still gaining fields; ignore any you do not recognise.

## Overview [#overview]

Search and list members associated with your organization. Results are automatically scoped to the calling key's organization — guests who have stayed at your properties or been linked to your org.

## Authentication [#authentication]

Requires a partner API key with the `partner:guests:read` scope, sent as `X-API-Key`.

## Query Parameters [#query-parameters]

<ParamField query="q" type="string">
  Search query across member name, email, and member code. Minimum 2 characters.
</ParamField>

<ParamField query="organizationId" type="string">
  External org ID (HXP UUID or WorkOS org ID). For superadmin keys only — org-scoped keys ignore this.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

<ParamField query="limit" type="number" default="20">
  Results per page (max 100)
</ParamField>

## Response [#response]

<ResponseField name="items" type="array" required>
  Member records
  <Expandable title="member object">
    <ResponseField name="member" type="object">
      `{ externalId, memberCode, displayName, firstName, lastName, avatarUrl, status, memberSince }`
    </ResponseField>
    <ResponseField name="profile" type="object | null">
      `{ dateOfBirth, gender, nationality, timezone, language }`
    </ResponseField>
    <ResponseField name="contacts" type="array">
      `[{ contactType, contactValue, isPrimary }]`
    </ResponseField>
    <ResponseField name="wallet" type="object | null">
      `{ walletId, spendablePoints, validBalance, creditBalance }`
    </ResponseField>
    <ResponseField name="loyalty" type="object">
      `{ tierLevel, tierName, lifetimePoints, currentYearPoints, pointsToNextTier, nextTierName }`
    </ResponseField>
    <ResponseField name="address" type="object | null">
      `{ street, city, state, postalCode, country }`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number" required>Total matching members</ResponseField>
<ResponseField name="offset" type="number" required>Current offset</ResponseField>
<ResponseField name="limit" type="number" required>Page size used</ResponseField>

<RequestExample>

```bash cURL
curl "https://api-prd.cf.journey.com/v1/partner/members?q=smith&limit=20" \
  -H "X-API-Key: jny_xxxx"
```

```typescript TypeScript
const { items, total } = await fetch(
  'https://api-prd.cf.journey.com/v1/partner/members?' + new URLSearchParams({ q: 'smith', limit: '20' }),
  { headers: { 'X-API-Key': apiKey } }
).then(r => r.json());

items.forEach(({ member, loyalty, wallet }) => {
  console.log(`${member.firstName} ${member.lastName} — ${loyalty.tierName}`);
  console.log(`Points: ${wallet?.spendablePoints ?? 'N/A'}`);
});
```

</RequestExample>

<ResponseExample>

```json 200 Response
{
  "items": [
    {
      "member": {
        "externalId": "01J5XYZ",
        "memberCode": "ABC123",
        "displayName": "John Smith",
        "firstName": "John",
        "lastName": "Smith",
        "avatarUrl": null,
        "status": "active",
        "memberSince": "2024-01-15T00:00:00Z"
      },
      "profile": {
        "dateOfBirth": null,
        "gender": null,
        "nationality": "US",
        "timezone": "America/New_York",
        "language": "en"
      },
      "contacts": [
        { "contactType": "email", "contactValue": "j***@example.com", "isPrimary": true }
      ],
      "wallet": {
        "walletId": "wal_01J5XYZ",
        "spendablePoints": 12500,
        "validBalance": 12500,
        "creditBalance": 0
      },
      "loyalty": {
        "tierLevel": 2,
        "tierName": "Silver",
        "lifetimePoints": 48000,
        "currentYearPoints": 12500,
        "pointsToNextTier": 12500,
        "nextTierName": "Gold"
      },
      "address": null
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}
```

</ResponseExample>