---
title: Group Onboarding | Vitable Docs
description: 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/index.md) to add, update, or remove members.

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

## Step 1: 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.

Terminal window

```
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:

```
{
  "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.

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/resources/plans/methods/list/index.md) for the full response schema.

## Step 2: Create a Group

Terminal window

```
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_`:

```
{
  "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/resources/groups/methods/create/index.md) 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/index.md). 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/index.md) 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/index.md) to submit your member roster.

## Related API Endpoints

- [`GET /v1/plans`](/api/resources/plans/methods/list/index.md) — List plans available to your organization
- [`POST /v1/groups`](/api/resources/groups/methods/create/index.md) — Create a group
- [`GET /v1/groups`](/api/resources/groups/methods/list/index.md) — List your organization’s groups
- [`GET /v1/groups/{id}`](/api/resources/groups/methods/retrieve/index.md) — Retrieve a single group
- [`PATCH /v1/groups/{id}`](/api/resources/groups/methods/update/index.md) — Update a group