Member Lifecycle

A member is a real person who receives care through Vitable on behalf of your organization. Members come into existence through member sync: you submit them in a roster for a group, and Vitable handles account creation, plan attachment, and authentication readiness from there.

This page covers what changes from the member’s perspective at each stage — and what stays put when they leave.

States at a Glance

State	How they get here	What’s true about them
Provisioning	Submitted in a sync for the first time, processing in progress	No account yet; can’t authenticate
Active	Sync succeeded; they appear in added_group_member_ids	Has an account, an active plan subscription, and belongs to a group
Removed	Their reference_id was omitted from the most recent sync	Account preserved; plan subscription ended; no longer subscribed to the group’s plan
Re-added	A subsequent sync brings their reference_id back	Same account; new plan subscription; subscribed to the group’s plan again
Blocked	They already have an active subscription under a different organization	Their existing subscription is preserved; the add is rejected and recorded in failures

Provisioning

When a new reference_id appears in a sync, Vitable:

1. Resolves the person. If the contact details (typically email plus date of birth) match someone Vitable already knows about, the existing person record is re-used so prior care history is retained. Otherwise a new person is created.
2. Attaches them to the group under the reference_id you supplied.
3. Starts a plan subscription on the plan_id from the sync row. The member is now considered active under that plan.

All of this happens asynchronously after the 202 response. Provisioning typically completes within seconds for a single member but can take longer for very large batches.

The 202 acceptance receipt is not a green light for downstream actions. If you intend to drive an in-product flow off “the member is now ready” (e.g. send them a welcome email, redirect to login), inspect the sync request’s results to confirm they appear in added_group_member_ids first.

Authentication

A newly provisioned member can sign in immediately via the passwordless flow — there is no separate “invite” or “activate” step driven from your side.

What you should know in the context of a sync:

• Initiating passwordless before the member is fully provisioned returns “user not found.” If you trigger sign-in from your own UI right after a sync, wait until they appear in added_group_member_ids (or retry after a short delay).
• The member’s email and phone come from the sync row. If the member updates them later inside Vitable, the next sync’s payload is not the source of truth for fields the member has edited themselves — but it is the source of truth for membership, plan, and reference identity.

Active State

Once active, a member:

• Belongs to exactly one group at a time (the group whose sync added them).
• Holds exactly one active plan subscription at a time.
• Can authenticate, access care, and use the integration in your product.

You can re-sync the same reference_id in subsequent payloads with no effect on their state — repeated syncs with an unchanged roster are no-ops. Field-level updates (name, phone, address) are applied to the existing record. The plan and group are unchanged.

Changing a member’s plan_id in a subsequent sync does not migrate them between plans. The sync is matched by reference_id and treats an unchanged reference as an unchanged member. To move a member to a different plan, contact your Vitable account manager — direct plan switching via sync is not currently supported.

Removal

When a reference_id previously subscribed in the group is omitted from a sync, Vitable:

1. Ends the member’s plan subscription. They are no longer billed against that plan and lose access to the care it provides going forward.
2. Removes them from the group’s current roster. They no longer appear in lists of currently subscribed members.
3. Preserves their account and their care history. Past appointments, messages, and records remain queryable for audit and continuity purposes.

A removed member’s prior subscription is retained as history. They cannot use the integration to access new care under that plan, but their record is not destroyed.

Re-adding a Member

If a previously removed member reappears in a subsequent sync — same reference_id, same group — Vitable starts a fresh plan subscription and reactivates their group membership. Their existing account is preserved, so they keep their care history, contact details (subject to whatever they’ve updated themselves), and any in-product state.

There is no separate “reactivate” endpoint. Re-syncing is the only mechanism.

The Cross-Organization Conflict

A member cannot hold two active plan subscriptions at the same time. If you sync a member who is already active under a different organization’s plan:

• Their existing subscription is preserved untouched — the other organization is not affected.
• Your add is rejected and recorded in the sync request’s failures with the reason "Member already has an active subscription!".
• The rest of your batch processes normally.

This protects against accidental double-subscription. To resolve it, coordinate with the other organization to end the member’s existing subscription, then re-submit your sync.

This conflict is identity-level, not group-level. Two of your own groups syncing the same person at the same time will hit the same wall — the second sync’s add fails. Pick one group as the source of truth per person.

Related Concepts

• Groups — the unit a member belongs to.
• Member Sync — how adds, removes, and updates are submitted.

Related API Endpoints

• POST /v1/groups/{id}/members/sync — Submit a member sync
• GET /v1/plans — List plans available to your organization