# Member

Members (internally `account_user`) are the **end-user records** in Gamopanda. Every streak log, challenge log, and reward log is tied to a member via `ownedById`. Before you can record activity for a user, they must exist as a member in the platform. You identify members using your own system's identifier — the `externalId`.

---

## How it works

1. **Log activity** — send `Streak Log` or `Challenge Log` entries with `ownedById` set to the member's Gamopanda `id` or `externalId`.
2. **Track progress** — the member's `Streak Progress`, `Challenge Progress`, and `Reward Log` records update automatically as logs are processed.
3. **Deactivate** — set `status` to `paused` to suspend a member without deleting their history.

---

## Fields

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `externalId` | string | ✅ | 256 | Your system's unique identifier for this user — e.g. a customer ID from your CRM, POS, or e-commerce platform. Unique per account. |
| `firstName` | string | ❌ | 256 | Member's first name |
| `lastName` | string | ❌ | 256 | Member's last name |
| `email` | email | ❌ | 320 | Member's email address |
| `phoneNumber` | phone | ❌ | 15 | Member's phone number in **E.164 format** — e.g. `+14155552671` |
| `status` | enum | ✅ | — | `draft` · `live` · `paused`. Only `live` members can earn progress. |

---

## The `externalId` — linking your system to Gamopanda

`externalId` is the bridge between your customer database and Gamopanda. Use whatever unique identifier your system already assigns to users — a UUID, an integer ID, an email address, or any other stable string.

```json
// Example: e-commerce customer ID
{ "externalId": "cust_8472910" }

// Example: UUID from your auth system
{ "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }

// Example: email as identifier
{ "externalId": "jane.doe@example.com" }
```

`externalId` is indexed and unique — two members cannot share the same value within an account.

---

## Member activity tabs

From the admin panel, each member record shows linked views of all their activity:

| Tab | Description |
|---|---|
| Streak Progress | Overall progress records across all streaks this member is enrolled in |
| Challenge Progress | Overall progress records across all challenges this member is enrolled in |
| Streak Log | Individual period-level log entries for streaks |
| Challenge Log | Individual period-level log entries for challenges |
| Reward Log | All reward entries issued to this member |

---

## Real-world examples

**🛍️ E-commerce — Log Streak Activity on purchase and syncs the member in the same API call**

Every time a customer completes a purchase, upsert them to ensure their record is current during logging streak activity:

```json
POST /schema/streak_log/record
{
  "streakId": "<streak-uuid>",
  "activityId": "made_a_purchase",
  "activityValue": 75.50,
  "ownedBy": {
    "externalId": "cust_8472910",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "status": "live"
  }
}
```

---

**☕ Food & Beverage — Log Challenge Activity on website visit and syncs the member in the same API call**

When a customer visits your website, upsert them to ensure their record is current during logging challenge activity:

```json
PUT /schema/challenge_log/record
{
  "challengeId": "<challenge-uuid>",
  "activityId": "visited_website",
  "activityValue": 1,
  "ownedBy": {
    "externalId": "cust_8472910",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "status": "live"
  }
}
```

---

**🏋️ Fitness — deactivating a cancelled subscription**

When a user cancels their subscription, pause their membership to stop them earning progress without deleting their history:

```json
PATCH /schema/account_user/record/{id}
{
  "status": "paused"
}
```

---

## Phone number format

`phoneNumber` must be in **E.164 format**:

- Starts with `+`
- Followed by country code and subscriber number
- No spaces, dashes, or parentheses
- Maximum 15 digits total

| ✅ Valid | ❌ Invalid |
|---|---|
| `+14155552671` | `(415) 555-2671` |
| `+447911123456` | `07911 123456` |
| `+34612345678` | `+34 612 345 678` |

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control, including upsert |
| End user | *(none)* | Not accessible |
| Guest user | *(none)* | Not accessible |

---

## Related resources

| Resource | Description |
|---|---|
| [Streak Progress](/streak_progress) | Per-member streak progress records |
| [Challenge Progress](/challenge_progress) | Per-member challenge progress records |
| [Streak Log](/streak_log) | Individual period-level streak activity entries for this member |
| [Challenge Log](/challenge_log) | Individual period-level challenge activity entries for this member |
| [Reward Log](/reward_log) | Rewards issued to this member |

---

## API reference

See the [API Reference](/api/member) for full request/response schemas and interactive examples for:

- `GET /schema/account_user/record` — list members
- `POST /schema/account_user/record` — create a member
- `GET /schema/account_user/record/{id}` — get a member by ID
- `PATCH /schema/account_user/record/{id}` — update a member
- `DELETE /schema/account_user/record/{id}` — delete a member