# Groups ## List groups `client.groups.list(GroupListParamsquery?, RequestOptionsoptions?): PageNumberPage` **get** `/v1/groups` Returns a paginated list of groups belonging to the authenticated organization. ### Parameters - `query: GroupListParams` - `limit?: number` Items per page (default: 20, max: 100) - `page?: number` Page number (default: 1) ### Returns - `Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const group of client.groups.list()) { console.log(group.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 `client.groups.create(GroupCreateParamsbody, RequestOptionsoptions?): GroupResponse` **post** `/v1/groups` Creates a new group scoped to the authenticated organization. ### Parameters - `body: GroupCreateParams` - `external_reference_id: string` - `name: string` ### Returns - `GroupResponse` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const groupResponse = await client.groups.create({ external_reference_id: 'mol_seg_001', name: 'Tier 1', }); console.log(groupResponse.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 `client.groups.retrieve(stringgroupID, RequestOptionsoptions?): 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 - `groupID: string` Unique group identifier (grp_*) ### Returns - `GroupResponse` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const groupResponse = await client.groups.retrieve('grp_abc123def456'); console.log(groupResponse.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 `client.groups.update(stringgroupID, GroupUpdateParamsbody?, RequestOptionsoptions?): 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 - `groupID: string` Unique group identifier (grp_*) - `body: GroupUpdateParams` - `external_reference_id?: string | null` - `name?: string | null` ### Returns - `GroupResponse` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const groupResponse = await client.groups.update('grp_abc123def456', { external_reference_id: 'mol_seg_001_v2', name: 'Tier 1 (renamed)', }); console.log(groupResponse.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 - `Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). ### Group Response - `GroupResponse` Response containing a single group resource. - `data: Group` - `id: string` Prefixed group identifier (`grp_`). - `created_at: string | null` 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 | null` Last-update timestamp (ISO 8601, UTC). # Members # Sync ## Submit group member sync `client.groups.members.sync.submit(stringgroupID, SyncSubmitParamsbody, RequestOptionsoptions?): 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 - `groupID: string` Unique group identifier (grp_*) - `body: SyncSubmitParams` - `members: Array` - `address: Address` - `address_line_1: string` - `city: string` - `state: string` - `zipcode: string` - `address_line_2?: string | null` - `date_of_birth: string` - `first_name: string` - `last_name: string` - `phone: string` - `plan_id: string` - `reference_id: string` - `email?: string | null` ### Returns - `SyncSubmitResponse` Response containing a single group member sync detail resource. - `data: Data` - `accepted_at: string` - `group_id: string` - `request_id: string` ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const response = await client.groups.members.sync.submit('grp_abc123def456', { members: [ { reference_id: 'EMP-001', first_name: 'Jane', last_name: 'Doe', date_of_birth: '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', }, }, ], }); console.log(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 `client.groups.members.sync.retrieve(stringrequestID, SyncRetrieveParamsparams, RequestOptionsoptions?): 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 - `requestID: string` - `params: SyncRetrieveParams` - `group_id: string` Unique group identifier (grp_*) ### Returns - `SyncRetrieveResponse` Response containing a single group member sync request detail resource. - `data: Data` - `accepted_at: string` - `completed_at: string | null` - `group_id: string` - `request_id: string` - `results: Results | null` - `added_group_member_ids: Array` - `failures: Array` - `operation: "add" | "remove"` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: string` - `reference_id: string` - `removed_group_member_ids: Array` ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const sync = await client.groups.members.sync.retrieve('request_id', { group_id: 'grp_abc123def456', }); console.log(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 - `SyncSubmitResponse` Response containing a single group member sync detail resource. - `data: Data` - `accepted_at: string` - `group_id: string` - `request_id: string` ### Sync Retrieve Response - `SyncRetrieveResponse` Response containing a single group member sync request detail resource. - `data: Data` - `accepted_at: string` - `completed_at: string | null` - `group_id: string` - `request_id: string` - `results: Results | null` - `added_group_member_ids: Array` - `failures: Array` - `operation: "add" | "remove"` * `add` - add * `remove` - remove - `"add"` - `"remove"` - `reason: string` - `reference_id: string` - `removed_group_member_ids: Array`