Manage Contacts

CRUD and reverse-lookup endpoints for the organization's contact directory. All contacts are org-scoped; the caller's organization is derived from the auth context.

POST /contacts

Create a new contact. At least one of given_name, family_name, company_name, or preferred_name must be non-empty (the vCard FN rule). If preferred_name is omitted it is synthesized from the other name fields.

Request body

Request example

JSON

Response (201)

Returns the created contact with memory_count: 0 and latest_memory: null (see Contact object).

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /contacts

List contacts. Contacts are organization-wide, so every agent in the org sees every contact.

Query parameters

Response (200)

Returns an array of contact objects, each with memory_count and latest_memory for its active generated memories.

Code examples

cURL

cURL

JavaScript

Python

GET /contacts/lookup

Reverse-lookup contacts by a single field. Useful for routing inbound email or phone calls to a known contact.

Query parameters

Exactly one of the following must be provided:

Response (200)

Returns an array of contact objects (up to 200). An empty array means no match.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /contacts/{contact_id}

Fetch a single contact by its UUID.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

PATCH /contacts/{contact_id}

Update a contact using JSON-merge-patch semantics:

• Omit a field to leave it unchanged
• Send a value to set it
• Send null on a nullable scalar to clear it
• Send a list to replace the stored list wholesale (no per-item merge)

After applying the patch, the server re-runs the FN rule against the merged state — if the update would leave every name field empty, the request 400s.

The response includes the contact's current active memory_count and latest_memory.

Path parameters

Request body

Any subset of the Create contact body fields. Organization administrators can also send review_status: "confirmed" to confirm an unreviewed contact. Agent-scoped callers cannot set review_status, and confirmed contacts cannot transition back to unreviewed.

Editing profile fields as an organization administrator also confirms an unreviewed contact. Confirmation records reviewed_at and reviewed_by in the response.

JSON

Code examples

cURL

cURL

JavaScript

Python

DELETE /contacts/{contact_id}

Delete a contact. Returns 204 No Content on success.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

Top-level fields

Email item

Phone item

Website item

Date item

Address item

All fields are optional free text.

Custom field item