hdls Contacts

hdls Contacts is a rich, standalone people database for your assistant — every contact with all their emails, phone numbers, freeform notes, and the lists they belong to. Where the CRM's contacts roll up to companies and deals, hdls Contacts is built for depth on the person: multiple emails and phones, a running note history, and flexible lists for segmentation.

The headline entity is the contact. Add as many emails, phones, and notes as you need, group people into lists, and pull the whole picture back with summarize_contact.

Common workflows

Capture a new person: create_contact → add_email / add_phone → add_note.
Segment your people: create_list → add_to_list for newsletters, events, or outreach.
Recall everything: summarize_contact for the record plus its recent timeline.

hdls Contacts is a headless, MCP-native contact management backend. It manages detailed people/contact records with emails, phones, notes, and lists, operated entirely through named tools your AI assistant calls. It stands in for tools like HubSpot Contacts, Apple Contacts — same job, no UI to run.

💬 Just ask

"Add Ada Lovelace with her email and phone, then add her to my newsletter list."

You don't call these tools yourself — just tell your assistant in plain English. Everything below is the reference for when you (or your assistant) want the exact details.

How Contacts is organized

The headline entity is the contact — start there, then attach the rest to it. Records connect by reference: an email links to a contact; a phone links to a contact; a note links to a contact; a list_member links to a list and a contact.

Entity	Purpose	Relates to
`contact`	The headline contact — every other record hangs off this.	—
`email`	An email linked to a `contact`.	`contact`
`phone`	A phone linked to a `contact`.	`contact`
`note`	A note linked to a `contact`.	`contact`
`list`	List records.	—
`list_member`	A list member linked to a `list` and a `contact`.	`list`, `contact`

Tools

Call these at https://hdls.ai/api/mcp/contacts. Required fields you must supply; optional fields refine the call. You never pass tenant_id — it is stamped server-side.

Create

Tool	What it does	Required	Optional
`create_contact`	Create a new contact.	—	`first_name`, `last_name`, `preferred_name`, `title`, `department`, `company_name`
`create_list`	Create a new list.	`name`	`description`, `data`

Update & advance

Tool	What it does	Required	Optional
`update_contact`	Update an existing contact by `id`.	`id`	`first_name`, `last_name`, `preferred_name`, `title`, `department`
`add_email`	Add an email.	`contact_id`, `value`	`label`, `is_primary`, `data`
`add_phone`	Add a phone.	`contact_id`, `value`	`label`, `is_primary`, `data`
`add_to_list`	Add a record to a list.	`list_id`, `contact_id`	`added_at`

Find & read

Tool	What it does	Required	Optional
`search_contacts`	Search contacts by free-text and/or column filters (tenant-scoped, paginated).	—	`search`, `filters`, `limit`, `orderBy`
`summarize_contact`	Fetch a contact plus its most recent timeline activity in one call.	`id`	`activityLimit`

Timeline

Tool	What it does	Required	Optional
`add_note`	Add a note.	`contact_id`, `body`	`author`

Field lists come from the product's live schema and are embedded in each tool's own description — read the tool description for the exact, current fields.

Field reference

Every field you can set on each record. Custom fields you add live alongside these in data.

`contact`

Field	Type	Notes
`first_name`	text
`last_name`	text
`preferred_name`	text
`title`	text	Display name.
`department`	text
`company_name`	text
`account_ref`	text
`primary_email`	text
`primary_phone`	text
`owner`	text
`lifecycle_stage`	text
`lead_source`	text
`status`	text	Lifecycle state.
`timezone`	text
`locale`	text
`do_not_contact`	true / false
`address_line1`	text
`address_line2`	text
`city`	text
`region`	text
`postal_code`	text
`country`	text
`linkedin`	text
`twitter`	text
`website`	text
`avatar_url`	text
`birthday`	date
`tags`	list	Free-form labels.
`data`	json	Free-form JSON — custom fields live here.
`created_by`	text

`email`

Field	Type	Required	Notes
`contact_id`	id	Yes	Links to a `contact`.
`value`	text	Yes
`label`	text
`is_primary`	true / false
`data`	json		Free-form JSON — custom fields live here.

`phone`

Field	Type	Required	Notes
`contact_id`	id	Yes	Links to a `contact`.
`value`	text	Yes
`label`	text
`is_primary`	true / false
`data`	json		Free-form JSON — custom fields live here.

`note`

Field	Type	Required	Notes
`contact_id`	id	Yes	Links to a `contact`.
`body`	text	Yes
`author`	text

`list`

Field	Type	Required	Notes
`name`	text	Yes	Display name.
`description`	text
`data`	json		Free-form JSON — custom fields live here.

`list_member`

Field	Type	Required	Notes
`list_id`	id	Yes	Links to a `list`.
`contact_id`	id	Yes	Links to a `contact`.
`added_at`	timestamp

Tailor it with custom fields

Add fields without a schema change. add_custom_field defines one, list_custom_fields shows what's defined, and promote_custom_field (admin) shares a personal field with the whole workspace. The value lives in each row's data (JSON) and is set and read through the normal record tools. See Products, tools & custom fields for the full model.

Roles & safety

Tenant isolation is automatic. Your credential is pinned to one workspace; you never pass tenant_id, and you can only ever see your own data (enforced by Postgres row-level security).
Role-gated. Permissions run reader < member < admin < owner. Installing a product and promoting a custom field workspace-wide need admin/owner.

Connect

On the concierge (https://hdls.ai/api/mcp), run install_product({ slug: "contacts" }) (admin/owner) to enable it for your workspace, then add https://hdls.ai/api/mcp/contacts as a connector in your assistant — see Connect your assistant.

A worked example

The literal call your assistant makes when you ask it to create the headline record:

Tool: create_contact
Arguments: {
  "first_name": "Ada",
  "last_name": "Lovelace"
}

See All products · Connect your assistant · Automation