> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.vitablehealth.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server.

# Groups

> What a group is in Vitable, how it relates to plans and members, and how its lifecycle works.

A **group** is a container for a set of members. You can create as many as you need, depending on your use case. Every member who receives care through Vitable belongs to one group at a time.

Groups are how you tell Vitable *which* members to provision, *which* plans to subscribe them to, and *when* to add or remove them. The sync endpoint operates on a single group at a time, so the way you organize your groups directly shapes how you author syncs.

## Mental Model

| Concept             | What it is                                                                              | Owned by                                       |
| ------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Organization        | Your integration as a whole — the entity that owns the API key                          | Vitable                                        |
| Plan                | A care offering linked to your organization. Defines what a subscribed member receives. | Vitable                                        |
| Group               | A named container for members under your organization                                   | Partner                                        |
| Member              | A person provisioned into a group via member sync                                       | Partner-supplied data; Vitable-managed account |
| Member subscription | The link between a member and a specific plan, with start and end times                 | Vitable                                        |

One organization can have many groups. One group can include members on different plans — each member's `plan_id` is specified per row at sync time, not at the group level.

## Identifying a Group

Every group has two identifiers:

* **`id`** — Vitable-issued, prefixed `grp_`. Stable for the lifetime of the group. Use it in every API call that targets the group.
* **`external_reference_id`** — your identifier. Optional but recommended. Use it to map a Vitable group back to a record in your own system.

You can filter groups by `external_reference_id` to avoid storing the `grp_` ID on your side if that's more convenient.

## Lifecycle

Groups are long-lived. You typically create a group once and keep it for as long as the underlying population exists. The supported operations:

| Operation    | Endpoint                            | Notes                                                                                                            |
| ------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Create       | `POST /v1/groups`                   | Returns the `grp_` ID and any provided `external_reference_id`.                                                  |
| List         | `GET /v1/groups`                    | Returns the groups under your organization.                                                                      |
| Retrieve     | `GET /v1/groups/{id}`               | Returns a single group by ID.                                                                                    |
| Update       | `PATCH /v1/groups/{id}`             | Rename a group or change its `external_reference_id`. Membership is **not** edited here — use the sync endpoint. |
| Sync members | `POST /v1/groups/{id}/members/sync` | The only way to add or remove members. See [Member Sync](/embedded_care/concepts/member-sync).                   |

> **Warning**
>
> There is no "delete group" endpoint. If a group is no longer in use, submit an empty sync (`{ "members": [] }`) to remove its roster, then stop using the group ID. Historical membership remains queryable for audit purposes.

## Related Concepts

* [Member Sync](/embedded_care/concepts/member-sync) — how the sync endpoint adds, removes, and matches members within a group.
* [Member Lifecycle](/embedded_care/concepts/member-lifecycle) — what happens to a member after they're synced into a group.

## Related API Endpoints

* [`POST /v1/groups`](/api/groups/create) — Create a group
* [`GET /v1/groups`](/api/groups/list) — List groups
* [`GET /v1/groups/{id}`](/api/groups/get) — Retrieve a single group
* [`PATCH /v1/groups/{id}`](/api/groups/update) — Update a group
* [`POST /v1/groups/{id}/members/sync`](/api/groups/members/sync/submit) — Submit a member sync