Group Onboarding

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 to add, update, or remove members.

Before you begin, make sure you have a valid API key. See Authentication 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.

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 for the full response schema.

Step 2: Create a Group

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 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. 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 concept page for a deeper look at how groups, plans, and member subscriptions relate.

What’s Next

Move on to Group Member Sync to submit your member roster.

Related API Endpoints

• GET /v1/plans — List plans available to your organization
• POST /v1/groups — Create a group
• GET /v1/groups — List your organization’s groups
• GET /v1/groups/{id} — Retrieve a single group
• PATCH /v1/groups/{id} — Update a group