Groups

Contact groups (Family, Work, VIP, etc.) — a contact can belong to multiple groups.

Contact groups (Family, Work, VIP, etc.). A contact can belong to multiple groups — the assigned group IDs are stored in the contact_group field. Groups appear in the sidebar with a name, color, and icon.

Service: contacts.groups

Fields

Field	Type	Required	Description
id	string	—	Primary key. Read-only, auto-generated
position	float		Fractional drag-sort position in the sidebar
enc_name	string	✅	Encrypted group name. Plain string after decryption
enc_color	string		Encrypted color identifier. Plain string after decryption. Values: primary · secondary · success · danger · warning · info · dark
enc_icon	string		Encrypted icon name. Plain string after decryption. Value is a Bootstrap Icons name (e.g. "people", "heart", "star")
created_at	string	—	ISO 8601 creation timestamp. Read-only
updated_at	string	—	ISO 8601 last update timestamp. Read-only
group_user_role	UserRole[]	✅	Access control + encryption keys

UserRole

Access control entry. Each recipient gets their own copy of the group’s encryption key, wrapped with their public key.

Field	Type	Required	Description
user_id	string	✅	Recipient user id
role	string	✅	Role identifier. Values: owner · editor · viewer
wrapped_content_key	string	✅	Group key wrapped for this recipient (base64)

find

List groups accessible to the authenticated user.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.find",
  "params": {
    "limit": 100,
    "fields": [
      "id", "position",
      "enc_name", "enc_color", "enc_icon",
      "group_user_role.user_id",
      "group_user_role.wrapped_content_key"
    ]
  },
  "id": 10
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291900",
        "position": 1000.0,
        "enc_name": "<base64>",
        "enc_color": "<base64>",
        "enc_icon": "<base64>",
        "group_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ]
      }
    ],
    "total": 1
  },
  "id": 10
}

findOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.findOneById",
  "params": {
    "id": "1920438291900"
  },
  "id": 11
}

create

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.create",
  "params": {
    "document": {
      "position": 3000.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>",
      "group_user_role": [
        { "user_id": "42", "role": "owner", "wrapped_content_key": "<base64>" }
      ]
    }
  },
  "id": 12
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291920",
    "enc_name": "<base64>",
    "created_at": "2026-05-13T18:30:00Z"
  },
  "id": 12
}

updateOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.updateOneById",
  "params": {
    "id": "1920438291900",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64-new>"
    }
  },
  "id": 13
}

replaceOneById

Full replacement — all writable fields must be provided. Unlike updateOneById, omitted fields are reset to defaults. Nested collections (group_user_role) are not accepted — use updateOneById to modify them.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.replaceOneById",
  "params": {
    "id": "1920438291900",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>"
    }
  },
  "id": 13
}

update

Batch update groups in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.update",
  "params": {
    "items": [
      { "id": "1920438291900", "document": { "position": 500.0 } },
      { "id": "1920438291905", "document": { "position": 1500.0 } }
    ]
  },
  "id": 15
}

deleteOneById

Delete a group. Contacts that belonged to this group are unlinked but not deleted.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.deleteOneById",
  "params": {
    "id": "1920438291900"
  },
  "id": 14
}

delete

Batch delete groups in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.groups.delete",
  "params": {
    "items": [
      { "id": "1920438291900" },
      { "id": "1920438291905" }
    ]
  },
  "id": 16
}