# Groups ## List groups `groups.list(**kwargs) -> PageNumberPage` **get** `/v1/groups` Returns a paginated list of groups belonging to the authenticated organization. ### Parameters - `limit: Integer` Items per page (default: 20, max: 100) - `page: Integer` Page number (default: 1) ### Returns - `class Group` - `id: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) page = vitable_connect.groups.list puts(page) ``` #### 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(**kwargs) -> GroupResponse` **post** `/v1/groups` Creates a new group scoped to the authenticated organization. ### Parameters - `external_reference_id: String` - `name: String` ### Returns - `class GroupResponse` Response containing a single group resource. - `data: Group` - `id: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) group_response = vitable_connect.groups.create(external_reference_id: "mol_seg_001", name: "Tier 1") puts(group_response) ``` #### 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(group_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: String` Unique group identifier (grp_*) ### Returns - `class GroupResponse` Response containing a single group resource. - `data: Group` - `id: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) group_response = vitable_connect.groups.retrieve("grp_abc123def456") puts(group_response) ``` #### 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(group_id, **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: String` Unique group identifier (grp_*) - `external_reference_id: String` - `name: String` ### Returns - `class GroupResponse` Response containing a single group resource. - `data: Group` - `id: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) group_response = vitable_connect.groups.update("grp_abc123def456") puts(group_response) ``` #### 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: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). ### Group Response - `class GroupResponse` Response containing a single group resource. - `data: Group` - `id: String` Prefixed group identifier (`grp_`). - `created_at: Time` 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: Time` Last-update timestamp (ISO 8601, UTC). # Members # Sync ## Submit group member sync `groups.members.sync.submit(group_id, **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: String` Unique group identifier (grp_*) - `members: Array[{ 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: String` - `date_of_birth: Date` - `first_name: String` - `last_name: String` - `phone: String` - `plan_id: String` - `reference_id: String` - `email: String` ### Returns - `class SyncSubmitResponse` Response containing a single group member sync detail resource. - `data: { accepted_at, group_id, request_id}` - `accepted_at: Time` - `group_id: String` - `request_id: String` ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) response = vitable_connect.groups.members.sync.submit( "grp_abc123def456", members: [ { address: {address_line_1: "123 Main Street", city: "San Francisco", state: "CA", zipcode: "94102"}, date_of_birth: "1990-05-15", first_name: "Jane", last_name: "Doe", phone: "4155550100", plan_id: "pln_abc123def456", reference_id: "EMP-001" } ] ) puts(response) ``` #### 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(request_id, **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: String` Unique group identifier (grp_*) - `request_id: String` ### Returns - `class SyncRetrieveResponse` Response containing a single group member sync request detail resource. - `data: { accepted_at, completed_at, group_id, 2 more}` - `accepted_at: Time` - `completed_at: Time` - `group_id: String` - `request_id: String` - `results: { added_group_member_ids, failures, removed_group_member_ids}` - `added_group_member_ids: Array[String]` - `failures: Array[{ operation, reason, reference_id}]` - `operation: :add | :remove` * `add` - add * `remove` - remove - `:add` - `:remove` - `reason: String` - `reference_id: String` - `removed_group_member_ids: Array[String]` ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) sync = vitable_connect.groups.members.sync.retrieve("request_id", group_id: "grp_abc123def456") puts(sync) ``` #### 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: { accepted_at, group_id, request_id}` - `accepted_at: Time` - `group_id: String` - `request_id: String` ### Sync Retrieve Response - `class SyncRetrieveResponse` Response containing a single group member sync request detail resource. - `data: { accepted_at, completed_at, group_id, 2 more}` - `accepted_at: Time` - `completed_at: Time` - `group_id: String` - `request_id: String` - `results: { added_group_member_ids, failures, removed_group_member_ids}` - `added_group_member_ids: Array[String]` - `failures: Array[{ operation, reason, reference_id}]` - `operation: :add | :remove` * `add` - add * `remove` - remove - `:add` - `:remove` - `reason: String` - `reference_id: String` - `removed_group_member_ids: Array[String]`