Skip to content

Activity Management Guide

Overview

Activities are the foundation of customer relationship tracking. Every interaction with leads, customers, and opportunities should be logged as an activity. This guide covers creating, scheduling, completing, and tracking all types of customer interactions to maintain comprehensive relationship history and ensure timely follow-ups.

Activity Types

The system supports various activity types representing different interaction methods:

TypeDescriptionCommon Use Cases
callPhone conversationsSales calls, check-ins, support calls
emailEmail communicationsProposals, follow-ups, correspondence
meetingIn-person or virtual meetingsDemos, QBRs, discovery meetings
taskAction items and to-dosResearch, documentation, internal tasks
noteGeneral notes and observationsMeeting notes, customer insights
demoProduct demonstrationsTrial sessions, feature showcases, POC
presentationFormal presentationsPitch decks, stakeholder briefings
proposalProposal-related activitiesProposal creation, delivery, review
follow_upFollow-up activitiesPost-meeting follow-ups, check-ins
quoteQuoting activitiesPrice quotation preparation and delivery
contractContract-related activitiesContract drafting, review, signing
appointmentScheduled appointmentsOn-site visits, scheduled calls
visitIn-person site visitsCustomer site visits, facility tours
webinarOnline seminarsProduct webinars, training sessions
trainingTraining sessionsCustomer training, onboarding sessions
supportSupport interactionsTechnical support, issue resolution
escalationEscalation eventsIssue escalation, management involvement
researchResearch activitiesMarket research, competitive analysis
otherMiscellaneous activitiesAny activity not covered above

Activity Status

Activities progress through different statuses:

StatusDescriptionActions Available
pendingScheduled but not yet startedComplete, Cancel, Reschedule, Update
in_progressCurrently being worked onComplete, Cancel, Update
completedSuccessfully finishedView, Update notes
cancelledCancelled before completionView, Recreate
deferredPostponed to a later dateReschedule, Cancel, Update
waitingBlocked on external dependencyComplete, Cancel, Reschedule

Activity Priority

Priority levels help organize workload:

PriorityDescriptionResponse Time
lowCan be deferredHandle when time permits
mediumStandard priorityHandle within normal timeframe
highImportant, time-sensitiveHandle promptly
urgentRequires immediate attentionHandle immediately
criticalBusiness-critical, blockingDrop everything, handle now

Creating Activities

Create Activity

Endpoint: POST /api/v1/crm/activities

Authentication: Required (Bearer token)

Request Body:

json
{
  "type": "call",
  "subject": "Follow-up Call - Proposal Discussion",
  "description": "Discuss proposal feedback, answer questions about pricing and implementation timeline. Focus on addressing concerns about legacy system integration.",
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyz823abc456def789ghi0",
  "contact_id": "01hwxyz123abc456def789ghi0",
  "assigned_user_id": "01hwxyz623abc456def789ghi0",
  "due_at": "2025-12-20T14:00:00Z",
  "duration_minutes": 30,
  "priority": "high",
  "location": "Phone",
  "reminder_at": "2025-12-20T13:45:00Z",
  "follow_up_required": true,
  "follow_up_date": "2025-12-23",
  "tags": ["proposal-discussion", "pricing-questions"],
  "custom_fields": {
    "call_purpose": "proposal_follow_up",
    "expected_outcome": "address_concerns"
  }
}

Required Fields:

  • type - Activity type
  • subject - Activity subject/title
  • activityable_type - Related entity type (lead, customer, opportunity, contact)
  • activityable_id - Related entity ID

Optional Fields:

  • description - Detailed activity description
  • contact_id - Specific contact involved
  • assigned_user_id - User responsible (defaults to creator)
  • due_at - When activity is scheduled
  • duration_minutes - Expected duration
  • priority - Priority level (defaults to medium)
  • location - Meeting location or phone number
  • reminder_at - When to send reminder
  • follow_up_required - Flag if follow-up needed
  • follow_up_date - When to follow up
  • tags - Activity categorization
  • is_billable - Whether activity is billable to customer
  • billable_rate - Hourly billing rate

Response (201 Created):

json
{
  "success": true,
  "message": "Activity created successfully",
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "type": "call",
    "status": "pending",
    "priority": "high",
    "subject": "Follow-up Call - Proposal Discussion",
    "description": "Discuss proposal feedback, answer questions about pricing and implementation timeline.",
    "activityable_type": "opportunity",
    "activityable_id": "01hwxyz823abc456def789ghi0",
    "activityable": {
      "id": "01hwxyz823abc456def789ghi0",
      "name": "Acme Corp - Enterprise Platform Implementation"
    },
    "contact_id": "01hwxyz123abc456def789ghi0",
    "contact": {
      "id": "01hwxyz123abc456def789ghi0",
      "name": "John Smith",
      "email": "john@acmecorp.com"
    },
    "assigned_user": {
      "id": "01hwxyz623abc456def789ghi0",
      "name": "Jane Manager",
      "email": "jane@yourcompany.com"
    },
    "due_at": "2025-12-20T14:00:00Z",
    "duration_minutes": 30,
    "reminder_at": "2025-12-20T13:45:00Z",
    "follow_up_required": true,
    "follow_up_date": "2025-12-23",
    "is_overdue": false,
    "created_at": "2025-12-17T22:00:00Z"
  }
}

Listing Activities

Get All Activities

Endpoint: GET /api/v1/crm/activities

Query Parameters:

  • type (string) - Filter by activity type
  • status (string) - Filter by status (pending, completed, cancelled, overdue)
  • priority (string) - Filter by priority
  • assigned_user_id (string) - Filter by assigned user
  • activityable_type (string) - Filter by related entity type
  • activityable_id (string) - Filter by related entity ID
  • due_date_from (date) - Due date range start
  • due_date_to (date) - Due date range end
  • search (string) - Search in subject and description
  • per_page (integer) - Results per page (default: 25)
  • page (integer) - Page number
  • sort_by (string) - Sort field (due_at, created_at, priority)
  • sort_direction (string) - Sort direction (asc, desc)
  • includes (string) - Relationships: assignedUser, contact, activityable

Example Request:

bash
GET /api/v1/crm/activities?status=pending&priority=high&assigned_user_id=01hwxyz623abc456def789ghi0&sort_by=due_at&sort_direction=asc

Response (200 OK):

json
{
  "success": true,
  "data": [
    {
      "id": "01hwxyzB23abc456def789ghi0",
      "type": "call",
      "status": "pending",
      "priority": "high",
      "subject": "Follow-up Call - Proposal Discussion",
      "due_at": "2025-12-20T14:00:00Z",
      "duration_minutes": 30,
      "assigned_user": {
        "id": "01hwxyz623abc456def789ghi0",
        "name": "Jane Manager"
      },
      "activityable_type": "opportunity",
      "activityable": {
        "id": "01hwxyz823abc456def789ghi0",
        "name": "Acme Corp - Enterprise Platform Implementation"
      },
      "is_overdue": false,
      "created_at": "2025-12-17T22:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 47,
    "last_page": 2
  }
}

Search Activities

Endpoint: GET /api/v1/crm/activities/search

Query Parameters:

  • q (string, required) - Search query (minimum 2 characters)
  • per_page (integer) - Results per page (default: 25)
  • page (integer) - Page number

Searches across subject and description fields.

Example Request:

bash
GET /api/v1/crm/activities/search?q=proposal+discussion

Viewing Activity Details

Endpoint: GET /api/v1/crm/activities/{id}

Query Parameters:

  • includes (string) - Relationships to include

Response (200 OK):

json
{
  "success": true,
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "type": "call",
    "status": "pending",
    "priority": "high",
    "subject": "Follow-up Call - Proposal Discussion",
    "description": "Discuss proposal feedback, answer questions about pricing and implementation timeline. Focus on addressing concerns about legacy system integration.",
    "activityable_type": "opportunity",
    "activityable_id": "01hwxyz823abc456def789ghi0",
    "activityable": {
      "id": "01hwxyz823abc456def789ghi0",
      "name": "Acme Corp - Enterprise Platform Implementation",
      "value": 150000.00,
      "stage": "proposal"
    },
    "contact_id": "01hwxyz123abc456def789ghi0",
    "contact": {
      "id": "01hwxyz123abc456def789ghi0",
      "name": "John Smith",
      "email": "john@acmecorp.com",
      "phone": "+1-555-0200"
    },
    "assigned_user": {
      "id": "01hwxyz623abc456def789ghi0",
      "name": "Jane Manager",
      "email": "jane@yourcompany.com"
    },
    "created_by": {
      "id": "01hwxyz623abc456def789ghi0",
      "name": "Jane Manager"
    },
    "due_at": "2025-12-20T14:00:00Z",
    "duration_minutes": 30,
    "location": "Phone: +1-555-0200",
    "reminder_at": "2025-12-20T13:45:00Z",
    "follow_up_required": true,
    "follow_up_date": "2025-12-23",
    "is_overdue": false,
    "is_billable": true,
    "billable_rate": 150.00,
    "tags": ["proposal-discussion", "pricing-questions"],
    "custom_fields": {
      "call_purpose": "proposal_follow_up",
      "expected_outcome": "address_concerns"
    },
    "created_at": "2025-12-17T22:00:00Z",
    "updated_at": "2025-12-17T22:00:00Z"
  }
}

Updating Activities

Endpoint: PUT /api/v1/crm/activities/{id} or PATCH /api/v1/crm/activities/{id}

Request Body (partial update):

json
{
  "due_at": "2025-12-20T15:00:00Z",
  "duration_minutes": 45,
  "description": "Extended call to include technical discussion with IT team. Now includes integration architect.",
  "tags": ["proposal-discussion", "pricing-questions", "technical-review"]
}

Response (200 OK):

json
{
  "success": true,
  "message": "Activity updated successfully",
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "due_at": "2025-12-20T15:00:00Z",
    "duration_minutes": 45,
    "updated_at": "2025-12-18T10:00:00Z"
  }
}

Completing Activities

Mark as Complete

Endpoint: POST /api/v1/crm/activities/{activityId}/complete

Request Body:

json
{
  "outcome": "Successful call. Addressed all pricing questions. Customer comfortable with proposed pricing. Discussed implementation timeline - they prefer February start. Next step: send revised timeline proposal.",
  "duration_minutes": 42,
  "follow_up_required": true,
  "follow_up_date": "2025-12-23",
  "tags": ["completed", "positive-outcome"]
}

Required Fields:

  • outcome - What was accomplished (optional but strongly recommended)

Optional Fields:

  • duration_minutes - Actual duration (if different from planned)
  • follow_up_required - Whether follow-up is needed
  • follow_up_date - When to follow up

Response (200 OK):

json
{
  "success": true,
  "message": "Activity completed successfully",
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "type": "call",
    "status": "completed",
    "subject": "Follow-up Call - Proposal Discussion",
    "outcome": "Successful call. Addressed all pricing questions. Customer comfortable with proposed pricing.",
    "completed_at": "2025-12-20T15:42:00Z",
    "duration_minutes": 42,
    "follow_up_required": true,
    "follow_up_date": "2025-12-23",
    "updated_at": "2025-12-20T15:42:00Z"
  }
}

Best Practice

Always document outcomes when completing activities. This creates valuable historical context for future interactions and helps team members understand relationship progression.

Cancelling Activities

Endpoint: POST /api/v1/crm/activities/{activityId}/cancel

Request Body:

json
{
  "reason": "Customer requested to reschedule. Will reschedule for next week after internal review.",
  "reschedule": true,
  "reschedule_date": "2025-12-27T14:00:00Z"
}

Response (200 OK):

json
{
  "success": true,
  "message": "Activity cancelled successfully",
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "status": "cancelled",
    "cancelled_at": "2025-12-19T10:00:00Z",
    "cancellation_reason": "Customer requested to reschedule. Will reschedule for next week after internal review.",
    "updated_at": "2025-12-19T10:00:00Z"
  }
}

Rescheduling Activities

Endpoint: POST /api/v1/crm/activities/{activityId}/reschedule

Request Body:

json
{
  "new_due_at": "2025-12-27T14:00:00Z",
  "reason": "Customer requested different time after internal meeting conflict",
  "update_reminder": true
}

Response (200 OK):

json
{
  "success": true,
  "message": "Activity rescheduled successfully",
  "data": {
    "id": "01hwxyzB23abc456def789ghi0",
    "due_at": "2025-12-27T14:00:00Z",
    "reminder_at": "2025-12-27T13:45:00Z",
    "previous_due_at": "2025-12-20T14:00:00Z",
    "rescheduled_count": 1,
    "updated_at": "2025-12-19T10:15:00Z"
  }
}

Deleting Activities

Endpoint: DELETE /api/v1/crm/activities/{id}

Response (200 OK):

json
{
  "success": true,
  "message": "Activity deleted successfully"
}

Soft Delete

Deleting an activity performs a soft delete. The record is retained for audit purposes but will no longer appear in standard listings. Consider cancelling instead to preserve the interaction history.

Business Scenarios

Scenario 1: Scheduling Sales Call Series

Context: New opportunity requires multiple touchpoints

Workflow:

bash
# 1. Schedule initial discovery call
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "Initial Discovery Call - Requirements Gathering",
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyz923abc456def789ghi0",
  "assigned_user_id": "01hwxyz623abc456def789ghi0",
  "due_at": "2025-12-22T10:00:00Z",
  "duration_minutes": 45,
  "priority": "high",
  "description": "Understand current challenges, technical environment, stakeholders, decision criteria, timeline, and budget.",
  "tags": ["discovery", "new-opportunity"]
}

# 2. Schedule demo
POST /api/v1/crm/activities
{
  "type": "demo",
  "subject": "Product Demo - Platform Capabilities",
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyz923abc456def789ghi0",
  "assigned_user_id": "01hwxyz623abc456def789ghi0",
  "due_at": "2025-12-29T14:00:00Z",
  "duration_minutes": 60,
  "priority": "high",
  "description": "Demonstrate key features aligned with requirements from discovery call. Include integration capabilities and customization options.",
  "tags": ["demo", "platform-overview"]
}

# 3. Schedule follow-up
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "Demo Follow-up - Answer Questions",
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyz923abc456def789ghi0",
  "assigned_user_id": "01hwxyz623abc456def789ghi0",
  "due_at": "2026-01-05T11:00:00Z",
  "duration_minutes": 30,
  "priority": "medium",
  "description": "Address questions from demo, discuss next steps, timeline for proposal.",
  "tags": ["follow-up", "demo-questions"]
}

# 4. Complete discovery call and update
POST /api/v1/crm/activities/01hwxyzC23abc456def789ghi0/complete
{
  "outcome": "Excellent discovery call. Key requirements: integration with Salesforce and SAP, support for 500 users, mobile access critical. Budget $150K-$200K. Timeline Q1 implementation. Decision makers: CTO (champion), CFO (budget authority), VP Ops (primary user).",
  "duration_minutes": 52,
  "tags": ["completed", "positive"]
}

# 5. Update opportunity based on discovery
PATCH /api/v1/crm/opportunities/01hwxyz923abc456def789ghi0
{
  "value": 175000.00,
  "probability": 40,
  "budget_confirmed": true,
  "authority_confirmed": true,
  "need_confirmed": true,
  "timeline_confirmed": true,
  "discovery_notes": "Requirements gathered. Integration with Salesforce + SAP required. 500 users. Mobile critical. Budget $150-200K. Q1 timeline.",
  "next_step": "Prepare demo focusing on integration capabilities"
}

Scenario 2: Managing Overdue Activities

Context: Several overdue activities need attention

Workflow:

bash
# 1. Get all overdue activities
GET /api/v1/crm/activities/overdue?assigned_user_id=01hwxyz623abc456def789ghi0

# 2. Prioritize by associated entity value
# High-value opportunity - reschedule immediately
POST /api/v1/crm/activities/01hwxyzD23abc456def789ghi0/reschedule
{
  "new_due_at": "2025-12-19T09:00:00Z",
  "reason": "High-priority opportunity. Rescheduling to earliest available slot.",
  "priority": "high"
}

# 3. Low-priority task - complete quickly
POST /api/v1/crm/activities/01hwxyzE23abc456def789ghi0/complete
{
  "outcome": "Task completed. Documentation updated with new customer information.",
  "duration_minutes": 15
}

# 4. Customer unresponsive - cancel and note
POST /api/v1/crm/activities/01hwxyzF23abc456def789ghi0/cancel
{
  "reason": "Customer unresponsive to 3 contact attempts. Will re-engage next month.",
  "reschedule": false
}

# 5. Update customer status if pattern emerges
PATCH /api/v1/crm/customers/01hwxyz423abc456def789ghi0
{
  "status": "at_risk",
  "notes": "Customer unresponsive for 14 days. Multiple missed calls. May be evaluating alternatives.",
  "tags": ["at-risk", "unresponsive"]
}

Scenario 3: Post-Meeting Follow-up Workflow

Context: QBR meeting completed, need to log and create follow-ups

Workflow:

bash
# 1. Complete meeting activity
POST /api/v1/crm/activities/01hwxyzG23abc456def789ghi0/complete
{
  "outcome": "Productive QBR. Reviewed Q4 usage metrics (85% adoption, 92% satisfaction). Discussed expansion to additional departments. Identified training needs for advanced features. Customer expressed interest in premium support tier.",
  "duration_minutes": 90,
  "follow_up_required": true,
  "follow_up_date": "2025-12-27",
  "tags": ["qbr", "completed", "expansion-opportunity"]
}

# 2. Create expansion opportunity
POST /api/v1/crm/opportunities
{
  "name": "Customer 575 - Department Expansion + Premium Support",
  "customer_id": "01hwxyz523abc456def789ghi0",
  "value": 85000.00,
  "expected_close_date": "2026-02-28",
  "stage": "qualification",
  "description": "Expand to 3 additional departments (250 additional users) + premium support tier upgrade.",
  "source": "qbr_meeting",
  "tags": ["expansion", "upsell"]
}

# 3. Schedule follow-up for training
POST /api/v1/crm/activities
{
  "type": "task",
  "subject": "Arrange Advanced Features Training",
  "activityable_type": "customer",
  "activityable_id": "01hwxyz523abc456def789ghi0",
  "assigned_user_id": "01hwxyzH23abc456def789ghi0",
  "due_at": "2025-12-23T10:00:00Z",
  "priority": "medium",
  "description": "Coordinate with training team to schedule advanced features workshop for Customer 575. Focus on reporting and automation features.",
  "tags": ["training", "customer-success"]
}

# 4. Schedule expansion discussion
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "Expansion Discussion - Additional Departments",
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyzI23abc456def789ghi0",
  "contact_id": "01hwxyz223abc456def789ghi0",
  "assigned_user_id": "01hwxyz623abc456def789ghi0",
  "due_at": "2025-12-27T14:00:00Z",
  "duration_minutes": 45,
  "priority": "high",
  "description": "Discuss expansion plan, user requirements for new departments, timeline, and premium support benefits.",
  "tags": ["expansion", "upsell"]
}

# 5. Create note summarizing action items
POST /api/v1/crm/activities
{
  "type": "note",
  "subject": "QBR Action Items - Customer 575",
  "activityable_type": "customer",
  "activityable_id": "01hwxyz523abc456def789ghi0",
  "status": "completed",
  "description": "Action items from QBR:\n1. Arrange advanced features training (Owner: Customer Success)\n2. Discuss expansion to 3 additional departments (Owner: Sales)\n3. Send premium support tier information (Owner: Sales)\n4. Follow up on API integration questions (Owner: Technical Support)\n5. Next QBR scheduled for March 2026",
  "tags": ["action-items", "qbr"],
  "completed_at": "2025-12-20T16:00:00Z"
}

Best Practices

1. Log Every Interaction

What to Log:

  • All customer/lead calls
  • Meetings (in-person and virtual)
  • Significant email exchanges
  • Demo sessions
  • Follow-up attempts

Why:

  • Creates complete relationship history
  • Enables team collaboration
  • Supports handoffs and transitions
  • Provides context for future interactions

2. Be Specific in Subject Lines

Good Examples:

  • "Follow-up Call - Pricing Discussion with CFO"
  • "Demo - Integration Capabilities for SAP Environment"
  • "QBR - Q4 2025 Performance Review"

Bad Examples:

  • "Call"
  • "Meeting with customer"
  • "Follow up"

3. Document Outcomes

Always Include:

  • What was discussed
  • Decisions made
  • Action items identified
  • Next steps agreed upon
  • Customer sentiment/feedback

Example Outcome:

Successful call. Addressed concerns about implementation timeline.
Customer agreed to 8-week timeline if we provide dedicated PM.
Action items:
1. Send revised SOW with PM included
2. Schedule kickoff for Jan 15
3. Introduce PM to customer next week
Next step: Send SOW by Dec 22, customer will review with team.

4. Set Realistic Due Dates

Considerations:

  • Your availability
  • Customer availability
  • Dependencies on others
  • Buffer time for preparation
  • Time zones

Avoid:

  • Over-scheduling (too many activities same day)
  • Under-estimating duration
  • Back-to-back activities without prep time

5. Use Reminders

Reminder Timing:

  • Calls: 15 minutes before
  • Meetings: 30-60 minutes before
  • Tasks: 1 day before due date
  • Demos: 1 day before (for preparation)

6. Tag Appropriately

Useful Tags:

  • Outcome-based: positive, concerns-raised, objections
  • Stage-based: discovery, demo, proposal, closing
  • Priority: urgent, high-value, strategic
  • Type: technical, pricing, executive

7. Complete Activities Promptly

Timing:

  • Complete activities same day when possible
  • Don't let activities sit in "pending" past due date
  • Document outcomes while fresh
  • Create follow-ups immediately

8. Review Weekly

Weekly Activity Review:

  • All overdue activities - reschedule or cancel
  • Upcoming week's activities - preparation needed?
  • Completed activities - follow-ups created?
  • Activity load - balanced across week?

Troubleshooting

Cannot Create Activity

Error: "Related entity not found"

Cause: Invalid activityable_type or activityable_id

Solution:

bash
# Verify entity exists first
GET /api/v1/crm/opportunities/01hwxyz823abc456def789ghi0
GET /api/v1/crm/customers/01hwxyz223abc456def789ghi0

# Then create activity with valid IDs
POST /api/v1/crm/activities
{
  "activityable_type": "opportunity",
  "activityable_id": "01hwxyz823abc456def789ghi0",
  ...
}

Activity Not Appearing in Lists

Issue: Activity created but not visible

Possible Causes:

  • Assigned to different user than viewing
  • Due date outside filtered range
  • Status filter excluding it

Solution:

bash
# Remove filters to find activity
GET /api/v1/crm/activities?search={subject}

# Or get by ID directly
GET /api/v1/crm/activities/{id}

Too Many Overdue Activities

Issue: Overwhelmed by overdue backlog

Actions:

bash
# 1. Get full list
GET /api/v1/crm/activities/overdue

# 2. Bulk cancel low-priority/stale activities
POST /api/v1/crm/activities/bulk-actions
{
  "action": "cancel",
  "activity_ids": ["01hwxyzJ23abc456def789ghi0", "01hwxyzK23abc456def789ghi0", "01hwxyzL23abc456def789ghi0"],
  "parameters": {
    "reason": "Stale activity, no longer relevant"
  }
}

# 3. Reschedule high-priority activities
POST /api/v1/crm/activities/01hwxyzM23abc456def789ghi0/reschedule
{
  "new_due_at": "2025-12-19T10:00:00Z"
}

# 4. Complete quick tasks immediately
POST /api/v1/crm/activities/01hwxyzN23abc456def789ghi0/complete
{
  "outcome": "Task completed"
}

Documentation for SynthesQ CRM/ERP Platform