---
name: contactdb
description: ContactDB REST API reference. Use when resolving people to contact_ids, searching contacts by name/email, or accessing relationships, notes, and platform identities.
user-invocable: false
---

# ContactDB API Reference

ContactDB is the people directory. It stores contacts, their platform identities, relationships, notes, and links. Every person across all data sources resolves to a single ContactDB `contact_id`.

**Base URL:** `http://localhost:42000/contactdb-api` (via Caddy) or `http://localhost:42800` (direct)

## Core Entities

### Contact

The central entity — represents a person.

| Field                | Type                | Description                                    |
|----------------------|---------------------|------------------------------------------------|
| `id`                 | int                 | Unique contact ID                              |
| `name`               | string              | Display name                                   |
| `emails`             | EmailField[]        | `{type, value, preferred}`                     |
| `phones`             | PhoneField[]        | `{type, value, preferred}`                     |
| `bio`                | string?             | Short biography                                |
| `avatar_url`         | string?             | Profile image URL                              |
| `personal_info`      | PersonalInfo        | Birthday, partner, children, role, company, location, how_we_met |
| `interests`          | string[]            | Topics of interest                             |
| `values`             | string[]            | Personal values                                |
| `tags`               | string[]            | User-assigned tags                             |
| `profile_description`| string?             | Extended description                           |
| `is_placeholder`     | bool                | Auto-created stub (not yet fully resolved)     |
| `is_service_account` | bool                | Non-human account (bot, no-reply)              |
| `stats`              | ContactStats        | Interaction statistics (see below)             |
| `enrichment_data`    | dict                | Data from enrichment providers                 |
| `platform_identities`| PlatformIdentity[]  | Identities on various platforms                |
| `created_at`         | datetime            | When created                                   |
| `updated_at`         | datetime            | Last modified                                  |
| `merged_into_id`     | int?                | If merged, target contact ID                   |
| `deleted_at`         | datetime?           | Soft-delete timestamp                          |

### ContactStats

| Field                    | Type          | Description                          |
|--------------------------|---------------|--------------------------------------|
| `total_messages`         | int           | Total messages across platforms       |
| `platforms_count`        | int           | Number of platforms active on         |
| `last_interaction_at`    | string?       | ISO datetime of last interaction      |
| `interaction_count_30d`  | int           | Interactions in last 30 days          |
| `interaction_count_90d`  | int           | Interactions in last 90 days          |
| `hotness`                | HotnessScore? | Composite engagement score (0-100)   |

### PlatformIdentity

Links a contact to a specific platform account.

| Field              | Type      | Description                              |
|--------------------|-----------|------------------------------------------|
| `id`               | int       | Identity record ID                       |
| `contact_id`       | int       | Parent contact                           |
| `source`           | string    | Data provenance (e.g., `dataindex_zulip`)|
| `platform`         | string    | Platform name (e.g., `email`, `zulip`)   |
| `platform_user_id` | string    | User ID on that platform                 |
| `display_name`     | string?   | Name shown on that platform              |
| `avatar_url`       | string?   | Platform-specific avatar                 |
| `bio`              | string?   | Platform-specific bio                    |
| `extra_data`       | dict      | Additional platform-specific data        |
| `first_seen_at`    | datetime  | When first observed                      |
| `last_seen_at`     | datetime  | When last observed                       |

### Relationship

Tracks connections between contacts.

| Field                  | Type      | Description                          |
|------------------------|-----------|--------------------------------------|
| `id`                   | int       | Relationship ID                      |
| `from_contact_id`      | int       | Source contact                       |
| `to_contact_id`        | int       | Target contact                       |
| `relationship_type`    | string    | Type (e.g., "colleague", "client")   |
| `since_date`           | date?     | When relationship started            |
| `relationship_metadata`| dict      | Additional metadata                  |

### Note

Free-text notes attached to a contact.

| Field        | Type     | Description          |
|--------------|----------|----------------------|
| `id`         | int      | Note ID              |
| `contact_id` | int      | Parent contact       |
| `content`    | string   | Note text            |
| `created_by` | string   | Who wrote it         |
| `created_at` | datetime | When created         |

### Link

External URLs associated with a contact.

| Field        | Type     | Description              |
|--------------|----------|--------------------------|
| `id`         | int      | Link ID                  |
| `contact_id` | int      | Parent contact           |
| `type`       | string   | Link type (e.g., "github", "linkedin") |
| `label`      | string   | Display label            |
| `url`        | string   | URL                      |

## REST Endpoints

### GET `/api/contacts` — List/search contacts

Primary way to find contacts. Returns `{contacts: [...], total, limit, offset}`.

**Query parameters:**

| Parameter              | Type          | Description                                  |
|------------------------|---------------|----------------------------------------------|
| `search`               | string?       | Search in name and bio                       |
| `is_placeholder`       | bool?         | Filter by placeholder status                 |
| `is_service_account`   | bool?         | Filter by service account status             |
| `sort_by`              | string?       | `"hotness"`, `"name"`, or `"updated_at"`     |
| `min_hotness`          | float?        | Minimum hotness score (0-100)                |
| `max_hotness`          | float?        | Maximum hotness score (0-100)                |
| `platforms`            | string[]?     | Contacts with ALL specified platforms (AND)  |
| `last_interaction_from`| string?       | ISO datetime lower bound                     |
| `last_interaction_to`  | string?       | ISO datetime upper bound                     |
| `limit`                | int           | Max results (1-100, default 50)              |
| `offset`               | int           | Pagination offset (default 0)                |

### GET `/api/contacts/me` — Get self contact

Returns the platform operator's own contact record. **Call this first** in most workflows to get your own `contact_id`.

### GET `/api/contacts/{id}` — Get contact by ID

Get full details for a single contact by numeric ID.

### GET `/api/contacts/by-email/{email}` — Get contact by email

Look up a contact by email address.

### Other Endpoints

| Method | Path                                    | Description                      |
|--------|-----------------------------------------|----------------------------------|
| POST   | `/api/contacts`                         | Create contact                   |
| PUT    | `/api/contacts/{id}`                    | Update contact                   |
| DELETE | `/api/contacts/{id}`                    | Delete contact                   |
| POST   | `/api/contacts/merge`                   | Merge two contacts               |
| GET    | `/api/contacts/{id}/relationships`      | List relationships               |
| GET    | `/api/contacts/{id}/notes`              | List notes                       |
| GET    | `/api/contacts/{id}/links`              | List links                       |
| GET    | `/api/platform-identities/contacts/{id}`| List platform identities         |

## Usage Pattern

1. **Start with `GET /api/contacts/me`** to get the operator's contact ID
2. **Search by name** with `GET /api/contacts?search=Alice`
3. **Use contact IDs** from results as filters in DataIndex queries (`contact_ids` parameter)
4. **Paginate** large result sets with `offset` increments