internalai-agent/docs/contactdb-api.md

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/ (direct) or http://caddy/contactdb-api/ (via greywall sandbox)

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