Relationships API

All endpoints require authentication and relationships tool permissions (view, update, or manage as noted).

Relationship Profiles

Get Contact Relationship Profile

GET /api/relationships/contacts/:id/relationship

Returns the contact’s relationship profile. Auto-creates a profile if none exists, pre-populating the phone number from the contact record. Also returns whether Twilio is connected.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:view

Response: { profile, twilio_connected }

---

Update Contact Relationship Profile

PATCH /api/relationships/contacts/:id/relationship

Updates (or upserts) the contact’s relationship profile fields.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:update

Body fields (all optional):

Field	Type	Description
communication_preference	string	Preferred communication channel
communication_notes	string	Notes about communication
personal_notes	string	Personal notes
birthday	string	Birthday (MM-DD or full date)
birthday_year	number	Birth year
home_address	string	Home address
interests	string[]	Array of interests (stored as JSON)
dietary_requirements	string	Dietary requirements
preferred_name	string	Preferred name
assistant_name	string	Assistant’s name
assistant_email	string	Assistant’s email
phone_number	string	Phone number
whatsapp_number	string	WhatsApp number
twilio_opt_in	boolean	Opted in to Twilio messaging

Response: { profile }

---

Life Events

List Life Events

GET /api/relationships/contacts/:id/life-events

Returns all life events for a contact, ordered by event date descending.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:view

Response: { events }

---

Create Life Event

POST /api/relationships/contacts/:id/life-events

Creates a life event for a contact. Automatically creates an auto-action if auto_action_enabled is not false.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:update

Body:

Field	Type	Required	Description
event_type	string	Yes	Event type (e.g. birthday, anniversary)
title	string	Yes	Event title
event_date	string	No	Event date (ISO)
recurs_annually	boolean	No	Whether event recurs each year
description	string	No	Event description
auto_action_enabled	boolean	No	Create auto-action (default: true)
auto_action_days_before	number	No	Days before event to trigger action
company_id	string	No	Associated company ID

Response: { event } (201)

---

Update Life Event

PATCH /api/relationships/contacts/:id/life-events/:eventId

Permission: relationships:update

Body fields (all optional): event_type, event_date, recurs_annually, title, description, auto_action_enabled, auto_action_days_before

Response: { event }

---

Delete Life Event

DELETE /api/relationships/contacts/:id/life-events/:eventId

Permission: relationships:manage

Response: { ok: true }

---

Auto-Actions

List All Relationship Actions

GET /api/relationships/relationship-actions

Returns relationship actions scoped by access level:

• Executive/Head: all actions
• Manager: own + squad members’ actions
• Others: own actions only

Permission: relationships:view

Response: { actions }

Each action includes joined first_name, last_name, contact_email, company_name, and assigned_to_name.

---

List Contact Relationship Actions

GET /api/relationships/contacts/:id/relationship-actions

Returns actions for a specific contact.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:view

Response: { actions }

---

Create Relationship Action

POST /api/relationships/contacts/:id/relationship-actions

Creates a manual relationship action for a contact. Also mirrors the action to the action centre.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:update

Body:

Field	Type	Required	Description
title	string	Yes	Action title
action_type	string	Yes	Action type (e.g. gift, whatsapp, call, linkedin, card)
description	string	No	Action description
assigned_to_user_id	string	No	Assigned user (default: current user)
due_date	string	No	Due date (ISO)
message_body	string	No	Pre-drafted message body
company_id	string	No	Associated company ID

Response: { action } (201)

---

Update Relationship Action Status

PATCH /api/relationships/relationship-actions/:id

Updates the status of a relationship action. Syncs completion to the action centre.

Path parameters:

Param	Type	Description
id	string	Action ID

Permission: relationships:update

Body:

Field	Type	Required	Description
status	string	Yes	New status: done or dismissed

Response: { action }

---

Messaging (Twilio)

List Contact Messages

GET /api/relationships/contacts/:id/messages

Returns all messages for a contact, ordered by most recent first.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:view

Response: { messages }

---

Send Message

POST /api/relationships/contacts/:id/messages

Sends an SMS, WhatsApp, or MMS message to a contact via Twilio. Requires the contact to have opted in (twilio_opt_in) and a valid phone number.

Path parameters:

Param	Type	Description
id	string	Contact ID

Permission: relationships:update

Body:

Field	Type	Required	Description
channel	string	Yes	sms, whatsapp, or mms
body	string	Yes	Message text
media_url	string	No	Media URL (MMS only)
auto_action_id	string	No	Link to auto-action (marks it done on send)

Response: { message } (201)

Error responses:

• 403 — Contact has not opted in
• 400 — No phone number on record
• 500 — Twilio not configured
• 503 — Twilio is disabled

---

Partners

List Company Partners

GET /api/relationships/companies/:id/partners

Returns partners for a client company. The company must have a client_profiles record.

Path parameters:

Param	Type	Description
id	string	Company ID

Permission: relationships:view

Response: { partners }

---

Create Partner

POST /api/relationships/companies/:id/partners

Path parameters:

Param	Type	Description
id	string	Company ID

Permission: relationships:update

Body:

Field	Type	Required	Description
partner_company_name	string	Yes	Partner company name
partner_contact_name	string	No	Partner contact name
partner_contact_email	string	No	Partner contact email
relationship_type	string	No	Relationship type
estimated_deal_size	number	No	Estimated deal size
notes	string	No	Notes
contact_id	string	No	Linked contact ID

Response: { partner } (201)

---

Update Partner

PATCH /api/relationships/companies/:id/partners/:partnerId

Permission: relationships:update

Body fields (all optional): partner_company_name, partner_contact_name, partner_contact_email, relationship_type, estimated_deal_size, notes, contact_id

Response: { partner }

---

Delete Partner

DELETE /api/relationships/companies/:id/partners/:partnerId

Permission: relationships:manage

Response: { ok: true }

---

Client Relationship Summary

Get Client Relationship Summary

GET /api/relationships/clients/:companyId/relationship-summary

Returns a comprehensive relationship summary for a client company including contacts with communication preferences, upcoming events (next 90 days + recurring), pending actions, partners, and recent messages (last 10).

Path parameters:

Param	Type	Description
companyId	string	Company ID

Permission: relationships:view

Response: { contacts, events, actions, partners, messages }