# Groups ## List groups **get** `/v1/groups` Returns a paginated list of groups belonging to the authenticated organization. ### Query Parameters - `limit: optional number` Items per page (default: 20, max: 100) - `page: optional number` Page number (default: 1) ### Returns - `data: array of Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). - `pagination: Pagination` Pagination metadata for list responses. - `limit: number` Items per page - `page: number` Current page number - `total: number` Total number of items - `total_pages: number` Total number of pages ### Example ```http curl https://api.vitablehealth.com/v1/groups \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" ``` #### Response ```json { "data": [ { "id": "grp_abc123def456", "organization_id": "org_abc123def456", "name": "Tier 1", "external_reference_id": "mol_seg_001", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 } } ``` ## Create group **post** `/v1/groups` Creates a new group scoped to the authenticated organization. ### Body Parameters - `external_reference_id: string` - `name: string` ### Returns - `GroupResponse { data }` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). ### Example ```http curl https://api.vitablehealth.com/v1/groups \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" \ -d '{ "external_reference_id": "mol_seg_001", "name": "Tier 1" }' ``` #### Response ```json { "data": { "id": "grp_abc123def456", "organization_id": "org_abc123def456", "name": "Tier 1", "external_reference_id": "mol_seg_001", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" } } ``` ## Get group **get** `/v1/groups/{group_id}` Retrieves a single group by its prefixed ID. Returns 404 if the group does not belong to the authenticated organization. ### Path Parameters - `group_id: string` Unique group identifier (grp_*) ### Returns - `GroupResponse { data }` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). ### Example ```http curl https://api.vitablehealth.com/v1/groups/$GROUP_ID \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" ``` #### Response ```json { "data": { "id": "grp_abc123def456", "organization_id": "org_abc123def456", "name": "Tier 1", "external_reference_id": "mol_seg_001", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" } } ``` ## Update group **patch** `/v1/groups/{group_id}` Partially updates a group's name or external reference ID. Returns 404 if the group does not belong to the authenticated organization. ### Path Parameters - `group_id: string` Unique group identifier (grp_*) ### Body Parameters - `external_reference_id: optional string` - `name: optional string` ### Returns - `GroupResponse { data }` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). ### Example ```http curl https://api.vitablehealth.com/v1/groups/$GROUP_ID \ -X PATCH \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" ``` #### Response ```json { "data": { "id": "grp_abc123def456", "organization_id": "org_abc123def456", "name": "Tier 1 (renamed)", "external_reference_id": "mol_seg_001_v2", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-16T09:12:00Z" } } ``` ## Domain Types ### Group - `Group { id, created_at, external_reference_id, 3 more }` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). ### Group Response - `GroupResponse { data }` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: string` Stable identifier for this group in the integrator's own system. - `name: string` Human-readable group name. - `organization_id: string` Prefixed organization identifier (`org_`). - `updated_at: string` Last-update timestamp (ISO 8601, UTC). # Members # Sync ## Submit group member sync **post** `/v1/groups/{group_id}/members/sync` Submits a member sync payload for the specified group. Members in the payload will be queued for processing asynchronously. Returns HTTP 202 with the batch ID and acceptance timestamp. ### Path Parameters - `group_id: string` Unique group identifier (grp_*) ### Body Parameters - `members: array of { address, date_of_birth, first_name, 5 more }` - `address: { address_line_1, city, state, 2 more }` - `address_line_1: string` - `city: string` - `state: string` - `zipcode: string` - `address_line_2: optional string` - `date_of_birth: string` - `first_name: string` - `last_name: string` - `phone: string` - `plan_id: string` - `reference_id: string` - `email: optional string` ### Returns - `data: { accepted_at, group_id, request_id }` - `accepted_at: string` - `group_id: string` - `request_id: string` ### Example ```http curl https://api.vitablehealth.com/v1/groups/$GROUP_ID/members/sync \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" \ -d '{ "members": [ { "address": { "address_line_1": "123 Main Street", "city": "San Francisco", "state": "CA", "zipcode": "94102", "address_line_2": "Apt 4B" }, "date_of_birth": "1990-05-15", "first_name": "Jane", "last_name": "Doe", "phone": "4155550100", "plan_id": "pln_abc123def456", "reference_id": "EMP-001", "email": "jane.doe@acme.com" } ] }' ``` #### Response ```json { "data": { "request_id": "grpmsr_abc123def456", "group_id": "grp_abc123def456", "accepted_at": "2026-01-15T10:30:00Z" } } ``` ## Get group member sync request **get** `/v1/groups/{group_id}/members/sync/{request_id}` Retrieves a previously-submitted group member sync request by its `grpmsr_` ID. Returns the acceptance timestamp, completion timestamp (if processing has finished), and the per-member `results` once available. While processing is in flight, `completed_at` and `results` are `null`. ### Path Parameters - `group_id: string` Unique group identifier (grp_*) - `request_id: string` ### Returns - `data: { accepted_at, completed_at, group_id, 2 more }` - `accepted_at: string` - `completed_at: string` - `group_id: string` - `request_id: string` - `results: { added_group_member_ids, failures, removed_group_member_ids }` - `added_group_member_ids: array of string` - `failures: array of { operation, reason, reference_id }` - `operation: "add" or "remove"` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: string` - `reference_id: string` - `removed_group_member_ids: array of string` ### Example ```http curl https://api.vitablehealth.com/v1/groups/$GROUP_ID/members/sync/$REQUEST_ID \ -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY" ``` #### Response ```json { "data": { "request_id": "grpmsr_abc123def456", "group_id": "grp_abc123def456", "accepted_at": "2026-01-15T10:30:00Z", "completed_at": "2026-01-15T10:30:42Z", "results": { "added_group_member_ids": [ "grpmbr_abc123def456" ], "removed_group_member_ids": [ "grpmbr_xyz789ghi012" ], "failures": [ { "reference_id": "EMP-002", "operation": "add", "reason": "Invalid plan_id" } ] } } } ``` ## Domain Types ### Sync Submit Response - `SyncSubmitResponse { data }` Response containing a single group member sync detail resource. - `data: { accepted_at, group_id, request_id }` - `accepted_at: string` - `group_id: string` - `request_id: string` ### Sync Retrieve Response - `SyncRetrieveResponse { data }` Response containing a single group member sync request detail resource. - `data: { accepted_at, completed_at, group_id, 2 more }` - `accepted_at: string` - `completed_at: string` - `group_id: string` - `request_id: string` - `results: { added_group_member_ids, failures, removed_group_member_ids }` - `added_group_member_ids: array of string` - `failures: array of { operation, reason, reference_id }` - `operation: "add" or "remove"` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: string` - `reference_id: string` - `removed_group_member_ids: array of string`