Tags

Cross-group tags for organizing contacts.

Cross-group tags for organizing contacts. A tag can be assigned to any contact regardless of group.

Service: contacts.tags

Fields

Field	Type	Required	Description
id	string	—	Primary key. Read-only, auto-generated
owner_id	string	—	Owner user id. Read-only, auto-set on create
owner_wrapped_key	string	✅	Content key wrapped by owner’s account key (base64). Required on create
enc_name	string	✅	Encrypted tag name. Plain string after decryption
enc_color	string		Encrypted color identifier. Plain string after decryption. Values: primary · secondary · success · danger · warning · info · dark
created_at	string	—	ISO 8601 creation timestamp. Read-only
updated_at	string	—	ISO 8601 last update timestamp. Read-only

find

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.find",
  "params": {
    "limit": 100,
    "fields": [
      "id", "enc_name", "enc_color",
      "owner_id", "owner_wrapped_key"
    ]
  },
  "id": 20
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291800",
        "enc_name": "<base64>",
        "enc_color": "<base64>",
        "owner_id": "42",
        "owner_wrapped_key": "<base64>"
      }
    ],
    "total": 1
  },
  "id": 20
}

findOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.findOneById",
  "params": {
    "id": "1920438291800"
  },
  "id": 21
}

create

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.create",
  "params": {
    "document": {
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "owner_id": "42",
      "owner_wrapped_key": "<base64>"
    }
  },
  "id": 22
}

Response

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

updateOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.updateOneById",
  "params": {
    "id": "1920438291800",
    "document": {
      "enc_name": "<base64-new>",
      "enc_color": "<base64-new>"
    }
  },
  "id": 23
}

replaceOneById

Full replacement — all writable fields must be provided. Unlike updateOneById, omitted fields are reset to defaults.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.replaceOneById",
  "params": {
    "id": "1920438291800",
    "document": {
      "enc_name": "<base64>",
      "enc_color": "<base64>"
    }
  },
  "id": 23
}

update

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.update",
  "params": {
    "items": [
      { "id": "1920438291800", "document": { "enc_color": "<base64-new>" } }
    ]
  },
  "id": 25
}

deleteOneById

Delete a tag. The tag is automatically unlinked from all contacts that had it assigned.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.deleteOneById",
  "params": {
    "id": "1920438291800"
  },
  "id": 24
}

delete

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.tags.delete",
  "params": {
    "items": [
      { "id": "1920438291800" }
    ]
  },
  "id": 26
}