Skip to navigation
Embedded CareConcepts

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

ConceptWhat it isOwned by
OrganizationYour integration as a whole — the entity that owns the API keyVitable
PlanA care offering linked to your organization. Defines what a subscribed member receives.Vitable
GroupA named container for members under your organizationPartner
MemberA person provisioned into a group via member syncPartner-supplied data; Vitable-managed account
Member subscriptionThe link between a member and a specific plan, with start and end timesVitable

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:

OperationEndpointNotes
CreatePOST /v1/groupsReturns the grp_ ID and any provided external_reference_id.
ListGET /v1/groupsReturns the groups under your organization.
RetrieveGET /v1/groups/{id}Returns a single group by ID.
UpdatePATCH /v1/groups/{id}Rename a group or change its external_reference_id. Membership is not edited here — use the sync endpoint.
Sync membersPOST /v1/groups/{id}/members/syncThe 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.

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