161 lines
8.8 KiB
Markdown
161 lines
8.8 KiB
Markdown
---
|
|
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
|