> 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.

# Group Onboarding

> Create a group, the container your members belong to. Lists the plans you can subscribe them to and walks through creating your first group.

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.

This guide covers the first two steps of bringing members into Vitable: discovering which plans you can subscribe members to, and creating the group those members will live in. Once your group exists, move on to [Group Member Sync](/embedded_care/guides/group-member-sync) to add, update, or remove members.

Before you begin, make sure you have a valid API key. See [Authentication](/getting-started/authentication) for details.

#### List the Plans Available to You

A plan defines what care a member is subscribed to. Plans are linked to your organization by Vitable; you do not create them yourself. Every member sync references a `plan_id` per member, so the first thing to know is which plans your organization has access to.

```bash
curl -X GET https://api.vitablehealth.com/v1/plans \
  -H "Authorization: Bearer $VITABLE_API_KEY"
```

The response lists every plan currently available to your organization:

```json
{
  "data": [
    {
      "id": "pln_aBcDeFgHiJkLmNoPqRsTuV",
      "name": "Vitable — Standard"
    }
  ]
}
```

Store the `id` of each plan you intend to use. You will pass these as `plan_id` on each member when syncing.

> **Note**
>
> If you don't see a plan you expect, contact your Vitable account manager.
> Plans are linked to your organization on the Vitable side; partners cannot
> self-serve plan creation.

See the [List Plans endpoint](/api/plans/list) for the full response schema.

#### Create a Group

```bash
curl -X POST https://api.vitablehealth.com/v1/groups \
  -H "Authorization: Bearer $VITABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Cohort",
    "external_reference_id": "your-internal-id-123"
  }'
```

The response returns the new group's `id`, prefixed with `grp_`:

```json
{
  "data": {
    "id": "grp_zYxWvUtSrQpOnMlKjIhGfE",
    "name": "Q1 Cohort",
    "external_reference_id": "your-internal-id-123"
  }
}
```

The `external_reference_id` field lets you map this group to your own internal identifier. It is optional but recommended — it lets you look up the group later without storing the `grp_` ID on your side.

See the [Create Group endpoint](/api/groups/create) for the full request and response schema.

## What You Can Do With a Group

Once a group exists, you can:

* **Sync members in and out** of the group via [Group Member Sync](/embedded_care/guides/group-member-sync). This is the primary operation — adding, updating, and removing members all happen through one sync endpoint.
* **Rename the group** or change its `external_reference_id` with `PATCH /v1/groups/{id}`.
* **List and retrieve groups** with `GET /v1/groups` and `GET /v1/groups/{id}`.

See the [Groups](/embedded_care/concepts/groups) concept page for a deeper look at how groups, plans, and member subscriptions relate.

## What's Next

Move on to [Group Member Sync](/embedded_care/guides/group-member-sync) to submit your member roster.

## Related API Endpoints

* [`GET /v1/plans`](/api/plans/list) — List plans available to your organization
* [`POST /v1/groups`](/api/groups/create) — Create a group
* [`GET /v1/groups`](/api/groups/list) — List your organization's groups
* [`GET /v1/groups/{id}`](/api/groups/get) — Retrieve a single group
* [`PATCH /v1/groups/{id}`](/api/groups/update) — Update a group