# Groups ## List groups `groups.list(GroupListParams**kwargs) -> SyncPageNumberPage[Group]` **get** `/v1/groups` Returns a paginated list of groups belonging to the authenticated organization. ### Parameters - `limit: Optional[int]` Items per page (default: 20, max: 100) - `page: Optional[int]` Page number (default: 1) ### Returns - `class Group: …` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) page = client.groups.list() page = page.data[0] print(page.id) ``` #### 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 `groups.create(GroupCreateParams**kwargs) -> GroupResponse` **post** `/v1/groups` Creates a new group scoped to the authenticated organization. ### Parameters - `external_reference_id: str` - `name: str` ### Returns - `class GroupResponse: …` Response containing a single group resource. - `data: Group` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) group_response = client.groups.create( external_reference_id="mol_seg_001", name="Tier 1", ) print(group_response.data) ``` #### 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 `groups.retrieve(strgroup_id) -> GroupResponse` **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. ### Parameters - `group_id: str` Unique group identifier (grp_*) ### Returns - `class GroupResponse: …` Response containing a single group resource. - `data: Group` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) group_response = client.groups.retrieve( "grp_abc123def456", ) print(group_response.data) ``` #### 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 `groups.update(strgroup_id, GroupUpdateParams**kwargs) -> GroupResponse` **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. ### Parameters - `group_id: str` Unique group identifier (grp_*) - `external_reference_id: Optional[str]` - `name: Optional[str]` ### Returns - `class GroupResponse: …` Response containing a single group resource. - `data: Group` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) group_response = client.groups.update( group_id="grp_abc123def456", external_reference_id="mol_seg_001_v2", name="Tier 1 (renamed)", ) print(group_response.data) ``` #### 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 - `class Group: …` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). ### Group Response - `class GroupResponse: …` Response containing a single group resource. - `data: Group` - `id: str` Prefixed group identifier (`grp_`). - `created_at: Optional[datetime]` Group creation timestamp (ISO 8601, UTC). - `external_reference_id: str` Stable identifier for this group in the integrator's own system. - `name: str` Human-readable group name. - `organization_id: str` Prefixed organization identifier (`org_`). - `updated_at: Optional[datetime]` Last-update timestamp (ISO 8601, UTC). # Members # Sync ## Submit group member sync `groups.members.sync.submit(strgroup_id, SyncSubmitParams**kwargs) -> SyncSubmitResponse` **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. ### Parameters - `group_id: str` Unique group identifier (grp_*) - `members: Iterable[Member]` - `address: MemberAddress` - `address_line_1: str` - `city: str` - `state: str` - `zipcode: str` - `address_line_2: Optional[str]` - `date_of_birth: Union[null, null]` - `first_name: str` - `last_name: str` - `phone: str` - `plan_id: str` - `reference_id: str` - `email: Optional[str]` ### Returns - `class SyncSubmitResponse: …` Response containing a single group member sync detail resource. - `data: Data` - `accepted_at: datetime` - `group_id: str` - `request_id: str` ### Example ```python import os from datetime import date from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) response = client.groups.members.sync.submit( group_id="grp_abc123def456", members=[{ "reference_id": "EMP-001", "first_name": "Jane", "last_name": "Doe", "date_of_birth": date.fromisoformat("1990-05-15"), "email": "jane.doe@acme.com", "phone": "4155550100", "plan_id": "pln_abc123def456", "address": { "address_line_1": "123 Main Street", "address_line_2": "Apt 4B", "city": "San Francisco", "state": "CA", "zipcode": "94102", }, }], ) print(response.data) ``` #### Response ```json { "data": { "request_id": "grpmsr_abc123def456", "group_id": "grp_abc123def456", "accepted_at": "2026-01-15T10:30:00Z" } } ``` ## Get group member sync request `groups.members.sync.retrieve(strrequest_id, SyncRetrieveParams**kwargs) -> SyncRetrieveResponse` **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`. ### Parameters - `group_id: str` Unique group identifier (grp_*) - `request_id: str` ### Returns - `class SyncRetrieveResponse: …` Response containing a single group member sync request detail resource. - `data: Data` - `accepted_at: datetime` - `completed_at: Optional[datetime]` - `group_id: str` - `request_id: str` - `results: Optional[DataResults]` - `added_group_member_ids: List[str]` - `failures: List[DataResultsFailure]` - `operation: Literal["add", "remove"]` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: str` - `reference_id: str` - `removed_group_member_ids: List[str]` ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) sync = client.groups.members.sync.retrieve( request_id="request_id", group_id="grp_abc123def456", ) print(sync.data) ``` #### 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 - `class SyncSubmitResponse: …` Response containing a single group member sync detail resource. - `data: Data` - `accepted_at: datetime` - `group_id: str` - `request_id: str` ### Sync Retrieve Response - `class SyncRetrieveResponse: …` Response containing a single group member sync request detail resource. - `data: Data` - `accepted_at: datetime` - `completed_at: Optional[datetime]` - `group_id: str` - `request_id: str` - `results: Optional[DataResults]` - `added_group_member_ids: List[str]` - `failures: List[DataResultsFailure]` - `operation: Literal["add", "remove"]` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: str` - `reference_id: str` - `removed_group_member_ids: List[str]`