Crm

Monica CRM

Monica Personal CRM API integration for managing contacts, relationships, notes, activities, and more.

Setup

Create a .env file in your project root with:

MONICA_API_TOKEN=your_api_token_here
MONICA_API_URL=https://app.monicahq.com

Get your API token from: https://app.monicahq.com/settings

Quick Start

The script automatically loads configuration from .env:

# List all contacts
python scripts/monica_api.py contacts

# Add a new contact with phone and note
python scripts/monica_api.py add-contact "John Doe" --phone "1234567890" --note "New client"

# Find or create contact
python scripts/monica_api.py find-or-create "Jane Smith" --phone "9876543210"

Core Operations

Contacts

List contacts

python scripts/monica_api.py contacts --limit 50 --query "john"

Find a contact

python scripts/monica_api.py find "John Doe"

Get contact details

python scripts/monica_api.py get 123 --with-fields

Add contact (convenience command - finds or creates)

python scripts/monica_api.py add-contact "John Doe" --phone "1234567890" --email "john@example.com" --note "Met at conference"

Find or create contact

python scripts/monica_api.py find-or-create "Jane Smith" --phone "9876543210" --note "New lead"

Set tags for contact

python scripts/monica_api.py tags set 123 "VIP" "吃饭人"

Notes

Add note to contact

python scripts/monica_api.py add-note 123 "Had a great lunch meeting today"

Get contact's notes (via Python import)

from scripts.monica_api import MonicaAPI
api = MonicaAPI()
api.get_contact_notes(123, limit=20)

Activities

Create activity (via Python import)

from scripts.monica_api import MonicaAPI
api = MonicaAPI()
api.create_activity(
    activity_type_id=2,
    summary="Lunch meeting",
    description="Discussed project updates",
    happened_at="2025-01-15",
    contacts=[123, 456]
)

Tags

List tags

python scripts/monica_api.py tags list

Create a tag

python scripts/monica_api.py tags create "VIP"

Set tags for contact

python scripts/monica_api.py tags set 123 "VIP" "吃饭人"

Set tags via Python API

from scripts.monica_api import MonicaAPI
api = MonicaAPI()
api.set_contact_tags(contact_id=123, tags=['VIP', '吃饭人'])

Python API

Basic Usage

from scripts.monica_api import MonicaAPI

# Automatically loads from .env
api = MonicaAPI()

Key Methods

# Contacts
contacts = api.list_contacts(limit=50, query="john")
contact = api.find_contact("John Doe")
contact, created = api.find_or_create_contact("John", "Doe")
new_contact = api.create_contact(first_name="Jane", gender_id=2)

# Contact Fields (phone, email, etc.)
api.set_contact_field(contact_id, 'phone', '1234567890', is_favorite=True)
api.set_contact_field(contact_id, 'email', 'jane@example.com')

# Notes
note = api.create_note(body="Meeting notes", contact_id=123)

# Activities
activity = api.create_activity(
    activity_type_id=2,
    summary="Call with client",
    happened_at="2025-01-15",
    contacts=[123]
)

# Reminders
reminder = api.create_reminder(
    title="Follow up",
    date="2025-01-20",
    contact_id=123
)
reminders = api.list_reminders(limit=10)
specific_reminder = api.get_reminder(reminder_id=456)
api.delete_reminder(reminder_id=456)

# Tags
api.set_contact_tags(contact_id=123, tags=['VIP', '吃饭人'])
tag = api.create_tag(name='New Tag')
tags = api.list_tags()

Common Workflows

Adding a new client

python scripts/monica_api.py add-contact "Client Name" \
    --phone "1234567890" \
    --email "client@company.com" \
    --note "Interested in our services"

Recording an interaction

1. Find the contact: python scripts/monica_api.py find "Client Name"
2. Add a note: python scripts/monica_api.py add-note 123 "Discussed Q4 plans"
3. Optionally log an activity via Python API

Bulk contact lookup

# Search for contacts
python scripts/monica_api.py contacts --query "Smith"

Adding tags to a contact

# Find the contact first to get the ID
python scripts/monica_api.py find "John Doe"

# Set tags for the contact
python scripts/monica_api.py tags set 123 "VIP" "吃饭人"

Gender IDs

• 1 - Male
• 2 - Female
• 3 - Non-binary
• 4 - Other

Important Notes

• The script automatically detects and loads .env file from current or parent directories
• API URL automatically handles /api suffix - just use base URL
• All dates use YYYY-MM-DD format for activities
• Contact IDs are integers - pass as numbers, not strings
• The add-contact command finds existing contacts or creates new ones automatically

Known Issues & Workarounds

Notes API Issue (POST /notes/)

Problem: The Monica Notes API (POST /notes/) has a bug where it returns note data for a different contact than the one specified in contact_id. The request succeeds (HTTP 200) but the note is not associated with the intended contact.

Workaround: Use the contact's description field to store notes instead of the Notes API:

from scripts.monica_api import MonicaAPI
api = MonicaAPI()

# Update contact description (reliable method)
api.update_contact(contact_id, description="欠款1块钱")

Required fields for update_contact(): When updating a contact, you must include:

• first_name (from existing contact)
• gender_id (from existing contact)
• is_birthdate_known (boolean, usually False)
• is_deceased_date_known (boolean, usually False)
• is_partial (from existing contact, usually False)
• is_deceased (from existing contact, usually False)
• Plus any fields you want to update (e.g., description)

Resources

scripts/monica_api.py

Full-featured Python client with .env auto-loading and Cloudflare-compatible headers.

Key features:

• Auto-detects and loads .env file
• find_contact() - Smart contact search
• find_or_create_contact() - Idempotent contact creation
• set_contact_field() - Add phone, email, address, etc.
• All Monica API endpoints supported

references/api.md

Complete API endpoint reference with all parameters, request formats, and response structures.