Groups

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.

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 — how the sync endpoint adds, removes, and matches members within a group.
• Member Lifecycle — what happens to a member after they’re synced into a group.

Related API Endpoints

• POST /v1/groups — Create a group
• GET /v1/groups — List groups
• GET /v1/groups/{id} — Retrieve a single group
• PATCH /v1/groups/{id} — Update a group
• POST /v1/groups/{id}/members/sync — Submit a member sync