Contacts

Encrypted address book compatible with iOS (CNContact) and Android (ContactsContract) data models.

Encrypted address book compatible with iOS (CNContact) and Android (ContactsContract) data models. All personal data is encrypted client-side before reaching the server — the server only stores opaque AES-GCM blobs.

Each encrypted column holds a JSON-serialized value (object or array). Field projection lets clients request only the slices they need: mail → enc_name + enc_emails, messenger → enc_name + enc_phones, contacts-web detail → everything.

All methods use the JSON-RPC 2.0 protocol over WebSocket. See Enbox API for transport details, error codes, query operators, and encryption model.

Service: contacts.contacts

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 name object. See ContactName
`enc_org`	`string`		Encrypted organization object. See ContactOrg
`enc_phones`	`string`		Encrypted phone array. See PhoneEntry[]
`enc_emails`	`string`		Encrypted email array. See EmailEntry[]
`enc_addresses`	`string`		Encrypted address array. See ContactAddress[]
`enc_urls`	`string`		Encrypted URL array. See UrlEntry[]
`enc_dates`	`string`		Encrypted dates array. See DateEntry[]
`enc_social`	`string`		Encrypted social profiles array. See SocialProfile[]
`enc_ims`	`string?`		Encrypted IM profiles array. See IMProfile[]. Nullable
`enc_relations`	`string`		Encrypted relations array. See RelationEntry[]
`enc_notes`	`string?`		Encrypted free-text notes. Plain `string` after decryption. Nullable
`enc_photo`	`string?`		Encrypted photo. Plain `string` after decryption (data URI: `data:image/jpeg;base64,...`). Nullable
`created_at`	`string`	—	ISO 8601 creation timestamp. Read-only
`updated_at`	`string`	—	ISO 8601 last update timestamp. Read-only
`contact_group`	ContactGroup[]		Assigned groups
`contact_tag`	`string[]`		Assigned tag IDs

ContactGroup

Field	Type	Required	Description
`id`	`string`	—	Junction row id. Read-only. Include when updating existing assignments
`group_id`	`string`	✅	Group id
`group_wrapped_key`	`string?`		Content key wrapped by group key. Set when group is shared

Encrypted field schemas

Each enc_* column is an AES-GCM blob. After decryption the plaintext is a JSON value whose structure is documented below.

Danger: The server cannot validate encrypted field structures. Writing an incorrect schema will produce corrupted data for all clients. Follow the type definitions below exactly.

ContactName

Decrypted content of enc_name. Object.

Field	Type	Required	Description
`prefix`	`string`	✅	Name prefix (e.g. `"Dr."`, `"Mr."`)
`given`	`string`	✅	First / given name
`middle`	`string`	✅	Middle name
`family`	`string`	✅	Last / family name
`suffix`	`string`	✅	Name suffix (e.g. `"Jr."`, `"III"`)
`nickname`	`string`	✅	Nickname
`maiden`	`string`	✅	Maiden name
`phonetic_given`	`string`	✅	Phonetic given name (for CJK sorting)
`phonetic_middle`	`string`	✅	Phonetic middle name
`phonetic_family`	`string`	✅	Phonetic family name

Warning: All fields are required and must be present in the JSON object. Use "" (empty string) for fields without a value. At least one of given, family, or nickname must be non-empty for a meaningful display name.

ContactOrg

Decrypted content of enc_org. Object.

Field	Type	Required	Description
`organization`	`string`	✅	Company / organization name
`department`	`string`	✅	Department within the organization
`job_title`	`string`	✅	Job title / role
`phonetic_org`	`string`	✅	Phonetic organization name

Warning: All fields are required and must be present in the JSON object. Use "" (empty string) for fields without a value.

PhoneEntry

Decrypted content of enc_phones. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`mobile` · `iPhone` · `home` · `work` · `main` · `other`	Phone type
`value`	`string`	✅	—	Phone number (e.g. `"+1 555 0100"`)

EmailEntry

Decrypted content of enc_emails. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`personal` · `work` · `school` · `other`	Email type
`value`	`string`	✅	—	Email address

UrlEntry

Decrypted content of enc_urls. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`home` · `blog` · `portfolio` · `work` · `other`	URL type
`value`	`string`	✅	—	URL (e.g. `"https://example.com"`)

DateEntry

Decrypted content of enc_dates. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`birthday` · `anniversary` · `other`	Date type
`value`	`string`	✅	—	Date in `YYYY-MM-DD` format (e.g. `"1990-06-15"`)

RelationEntry

Decrypted content of enc_relations. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`spouse` · `partner` · `mother` · `father` · `parent` · `brother` · `sister` · `child` · `son` · `daughter` · `friend` · `assistant` · `manager` · `other`	Relation type
`value`	`string`	✅	—	Related person’s name

ContactAddress

Decrypted content of enc_addresses. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	`home` · `work` · `other`	Address type
`street`	`string`	✅	—	Street address (may include apartment/suite)
`sub_locality`	`string`	✅	—	Sub-locality (neighborhood, district)
`city`	`string`	✅	—	City
`sub_admin_area`	`string`	✅	—	Sub-administrative area (county)
`state`	`string`	✅	—	State / province / region
`postal_code`	`string`	✅	—	Postal / ZIP code
`country`	`string`	✅	—	Country display name
`iso_country_code`	`string`	✅	—	ISO 3166-1 alpha-2 code (e.g. `"US"`, `"DE"`)

SocialProfile

Decrypted content of enc_social. Array of objects.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	—	Display name of the service (e.g. `"Twitter"`)
`service`	`string`	✅	`Twitter` · `Telegram` · `Instagram` · `LinkedIn` · `GitHub` · `Signal` · `WhatsApp` · `Facebook`	Machine identifier of the social network
`value`	`string`	✅	—	Handle, username, or profile URL

IMProfile

Decrypted content of enc_ims. Array of objects. Nullable — the entire field may be null.

Field	Type	Required	Allowed values	Description
`label`	`string`	✅	—	Display name of the service (e.g. `"Skype"`)
`service`	`string`	✅	`Skype` · `Jabber` · `ICQ` · `other`	Machine identifier of the IM network
`value`	`string`	✅	—	Username or handle

find

List contacts with filtering, sorting, and pagination.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.find",
  "params": {
    "sort": [{ "field": "created_at", "dir": "desc" }],
    "limit": 100,
    "fields": [
      "id", "created_at", "updated_at",
      "enc_name", "enc_org", "enc_phones", "enc_emails", "enc_dates",
      "owner_id", "owner_wrapped_key",
      "contact_group.id", "contact_group.group_id", "contact_group.group_wrapped_key",
      "contact_tag.tag_id"
    ]
  },
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291738",
        "created_at": "2026-05-01T10:30:00Z",
        "updated_at": "2026-05-13T18:30:00Z",
        "enc_name": "<base64>",
        "enc_org": "<base64>",
        "enc_phones": "<base64>",
        "enc_emails": "<base64>",
        "enc_dates": "<base64>",
        "owner_id": "42",
        "owner_wrapped_key": "<base64>",
        "contact_group": [{"id": "1920438291950", "group_id": "1920438291900", "group_wrapped_key": null}],
        "contact_tag": ["1920438291800"]
      }
    ],
    "total": 128
  },
  "id": 1
}

findOneById

Fetch a single contact with all encrypted sections.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.findOneById",
  "params": {
    "id": "1920438291738",
    "fields": [
      "id", "created_at", "updated_at",
      "enc_name", "enc_org", "enc_phones", "enc_emails", "enc_dates",
      "enc_addresses", "enc_urls", "enc_social", "enc_ims",
      "enc_relations", "enc_notes", "enc_photo",
      "owner_id", "owner_wrapped_key",
      "contact_group.id", "contact_group.group_id", "contact_group.group_wrapped_key",
      "contact_tag.tag_id"
    ]
  },
  "id": 2
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291738",
    "created_at": "2026-05-01T10:30:00Z",
    "updated_at": "2026-05-13T18:30:00Z",
    "enc_name": "<base64>",
    "enc_org": "<base64>",
    "enc_phones": "<base64>",
    "enc_emails": "<base64>",
    "enc_dates": "<base64>",
    "enc_addresses": "<base64>",
    "enc_urls": "<base64>",
    "enc_social": "<base64>",
    "enc_ims": "<base64>",
    "enc_relations": "<base64>",
    "enc_notes": "<base64>",
    "enc_photo": "<base64>",
    "owner_id": "42",
    "owner_wrapped_key": "<base64>",
    "contact_group": [{"id": "1920438291950", "group_id": "1920438291900", "group_wrapped_key": null}],
    "contact_tag": ["1920438291800"]
  },
  "id": 2
}

create

Create a new contact. The server assigns id, created_at, and updated_at.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.create",
  "params": {
    "document": {
      "enc_name": "<base64>",
      "enc_org": "<base64>",
      "enc_phones": "<base64>",
      "enc_emails": "<base64>",
      "enc_dates": "<base64>",
      "enc_addresses": "<base64>",
      "enc_urls": "<base64>",
      "enc_social": "<base64>",
      "enc_relations": "<base64>",
      "enc_notes": "<base64>",
      "owner_id": "42",
      "owner_wrapped_key": "<base64>",
      "contact_group": [{"group_id": "1920438291900"}],
      "contact_tag": ["1920438291800"]
    }
  },
  "id": 3
}

Response

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

updateOneById

Partial update — only specified fields change; omitted fields are untouched. Nested collections are updated automatically: items with id are updated, items without id are created, items missing from the array are deleted.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.updateOneById",
  "params": {
    "id": "1920438291738",
    "document": {
      "enc_name": "<base64-new>",
      "enc_phones": "<base64-new>",
      "contact_group": [{"id": "1920438291950", "group_id": "1920438291900"}, {"group_id": "1920438291910"}]
    }
  },
  "id": 4
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291738",
    "enc_name": "<base64-new>",
    "enc_phones": "<base64-new>",
    "updated_at": "2026-05-13T18:45:00Z"
  },
  "id": 4
}

replaceOneById

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.replaceOneById",
  "params": {
    "id": "1920438291738",
    "document": {
      "enc_name": "<base64>",
      "enc_org": "<base64>",
      "enc_phones": "<base64>",
      "enc_emails": "<base64>",
      "enc_addresses": "<base64>",
      "enc_urls": "<base64>",
      "enc_dates": "<base64>",
      "enc_social": "<base64>",
      "enc_relations": "<base64>",
      "enc_notes": "<base64>"
    }
  },
  "id": 4
}

update

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.update",
  "params": {
    "items": [
      { "id": "1920438291738", "document": { "enc_org": "<base64-new>" } },
      { "id": "1920438291739", "document": { "enc_org": "<base64-new>" } }
    ]
  },
  "id": 5
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "affected": 2,
    "items": [
      { "id": "1920438291738", "enc_org": "<base64-new>" },
      { "id": "1920438291739", "enc_org": "<base64-new>" }
    ]
  },
  "id": 5
}

deleteOneById

Delete a contact. All group/tag assignments and access roles are deleted with it.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.deleteOneById",
  "params": {
    "id": "1920438291738"
  },
  "id": 6
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291738",
    "enc_name": "<base64>"
  },
  "id": 6
}

delete

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

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "contacts.contacts.delete",
  "params": {
    "items": [
      { "id": "1920438291738" },
      { "id": "1920438291739" }
    ]
  },
  "id": 7
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "affected": 2,
    "items": [
      { "id": "1920438291738" },
      { "id": "1920438291739" }
    ]
  },
  "id": 7
}