# 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`