> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Communities & Access Control

Communities are membership groups that gate access to resources and services. Members can receive booking quotas, access control grants, and exclusive booking permissions.

For general conventions, see [JSON-API Conventions](https://docs.anny.co/developers/guides/json-api-conventions.md). For authentication, see [Authentication](https://docs.anny.co/developers/guides/authentication.md).

***

## Prerequisites

* Admin API: Bearer token with admin access + `?o={organization_id}`
* Customer API: Authenticated customer account for membership and invite actions

***

## Concepts

| Entity | Description |
| - | - |
| **Community** | A named group with members, rules, and permissions |
| **Community Account** | A membership record linking a customer account to a community |
| **Community Invite** | An email invitation to join a community |
| **Booking Pass** | A quota voucher (e.g. "10x Yoga Class") granted to community members |
| **Account Pass** | A digital wallet pass (Apple/Google Wallet) for physical access |

### Member Roles

| Role | Permissions |
| - | - |
| `member` | Standard access according to community rules |
| `manager` | Can manage members and settings |
| `visitor` | Limited/temporary access |

### Member Statuses

| Status | Meaning |
| - | - |
| `accepted` | Active member |
| `pending` | Awaiting approval |

Memberships can be time-limited via `start_date` and `end_date` fields on the community account.

***

## Creating a Community (Admin)

```http theme={null}
POST /api/v1/communities?o={org_id}

{
  "data": {
    "type": "communities",
    "attributes": {
      "name": "Premium Members",
      "slug": "premium-members",
      "is_private": true,
      "allow_customer_requests": true,
      "auto_join_enabled": false,
      "include_all_services": false
    }
  }
}
```

### Key Attributes

| Attribute | Type | Description |
| - | - | - |
| `name` | string | Display name |
| `slug` | string | URL-friendly identifier |
| `is_private` | boolean | Hidden from public listing if `true` |
| `allow_customer_requests` | boolean | Customers can request to join |
| `auto_join_enabled` | boolean | Enable automatic membership rules |
| `include_all_services` | boolean | Members can access all services |
| `welcome_text` | string | Shown to members on join |

### Resource meta

Authenticated community resource objects (primary **and** [included](https://docs.anny.co/developers/guides/json-api-conventions.md#including-related-resources)) expose:

| Meta | Type | Description |
| - | - | - |
| `members_count` | integer | Number of **active** members (memberships whose start/end window includes now). This is the stored `active_community_accounts_count` on the community. Expired or not-yet-started memberships are excluded. |

```http theme={null}
GET /api/v1/communities?o={org_id}
GET /api/v1/resources/{resource_id}?o={org_id}&include=communities
GET /api/v1/services/{service_id}?o={org_id}&include=communities
```

Listing membership rows (`community-accounts`) is a different endpoint and is not how this count is produced.

***

## Inviting Members (Admin)

Send email invitations to join:

```http theme={null}
POST /api/v1/communities/{community_id}/invites?o={org_id}

{
  "emails": ["jane@example.com", "john@example.com"],
  "role": "member",
  "body": "You've been invited to our Premium Members community!",
  "start_date": "2026-04-01",
  "end_date": "2026-12-31",
  "silent": false
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `emails` | string\[] | Yes | Email addresses to invite |
| `role` | string | No | Member role (default: `member`) |
| `body` | string | No | Custom invitation message |
| `start_date` | string | No | Membership start date |
| `end_date` | string | No | Membership expiration date |
| `silent` | boolean | No | `true` to skip sending invitation emails |

If an email matches an existing customer account, the membership is created immediately (no pending invite). A second invite to the same email widens the existing pending invite instead of creating another row.

Booking auto-join reuses an overlapping or covering membership and consumes leftover pending invites for that email, so the members page does not list the same person as both invite and member. Non-overlapping sequential windows (for example two separate week-long visits) still create separate memberships.

### List invitations

```http theme={null}
GET /api/v1/community-invites?o={org_id}&filter[search]=jane@&filter[open]=true
```

| Filter | Description |
| - | - |
| `filter[email]` | Exact invite email |
| `filter[search]` | Case-insensitive substring match on the invite email |
| `filter[open]` | Open (not yet accepted) invites |
| `filter[accepted_at]` | Accepted-at timestamp |
| `filter[expiry]` | Invite expiry |

Allowed sort: `email`, `created_at`, `accepted_at`. Allowed include: `community`, `user`, `organization`, `organization.logo_image`, `joined_through`.

### Resend an Invitation

```http theme={null}
GET /api/v1/community-invites/{invite_id}/resend?o={org_id}
```

***

## Auto-Join Rules

Communities can automatically add members based on:

| Trigger | Description |
| - | - |
| **Booking** | Customer books a service linked to the community |
| **Subscription** | Customer claims a plan subscription associated with the community |
| **Email Domain** | Customer's email domain matches a verified domain ownership |

Configure via the `auto_join_settings` attribute on the community resource. Use the sync endpoint to apply rules retroactively:

```http theme={null}
GET /api/v1/communities/{community_id}/sync-auto-join?o={org_id}
```

Returns the number of newly added members.

***

## Customer Membership Actions

Community membership actions are documented in the customer API, not the public API.

### Leave a Community

```http theme={null}
GET /api/v1/communities/{community_id}/leave
```

### Accept an Invite

```http theme={null}
POST /api/v1/community-invites/{invite_id}/accept
```

***

## Common Errors

| Error | Cause | Solution |
| - | - | - |
| `403` — not a member | Action requires community membership | Join the community first |
| `422` — community is private | Cannot join a private community directly | Request an invitation from an admin |
| `422` — already a member | Duplicate join attempt | Check membership status before joining |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.