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:

Type	Description	Common Use Cases
Call	Phone conversations	Sales calls, check-ins, support calls, follow-ups
Meeting	In-person or virtual meetings	Demos, QBRs, discovery meetings, presentations
Email	Email communications	Proposals, follow-ups, newsletters, correspondence
Task	Action items and to-dos	Research, documentation, preparation, internal tasks
Note	General notes and observations	Meeting notes, customer insights, observations
Demo	Product demonstrations	Trial sessions, feature showcases, POC demonstrations
Follow-up	Follow-up activities	Post-meeting follow-ups, check-ins, status updates
Other	Miscellaneous activities	Any activity not covered by above types

Activity Status

Activities progress through different statuses:

Status	Description	Actions Available
Pending	Scheduled but not yet started	Complete, Cancel, Reschedule, Update
In Progress	Currently being worked on	Complete, Cancel, Update
Completed	Successfully finished	View, Update notes
Cancelled	Cancelled before completion	View, Recreate
Overdue	Past due date and not completed	Complete, Reschedule, Cancel

Activity Priority

Priority levels help organize workload:

Priority	Description	Response Time
High	Urgent, time-sensitive	Handle immediately
Medium	Standard priority	Handle within normal timeframe
Low	Can be deferred	Handle when time permits

Creating Activities

Create Activity

Endpoint: POST /api/v1/crm/activities

Authentication: Required (Bearer token)

Request Body:

{
  "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": 890,
  "contact_id": 123,
  "assigned_user_id": 7,
  "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):

{
  "message": "Activity created successfully",
  "data": {
    "id": 2001,
    "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": 890,
    "activityable": {
      "id": 890,
      "name": "Acme Corp - Enterprise Platform Implementation"
    },
    "contact_id": 123,
    "contact": {
      "id": 123,
      "name": "John Smith",
      "email": "john@acmecorp.com"
    },
    "assigned_user": {
      "id": 7,
      "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 (integer) - Filter by assigned user
• activityable_type (string) - Filter by related entity type
• activityable_id (integer) - 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:

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

Response (200 OK):

{
  "data": [
    {
      "id": 2001,
      "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": 7,
        "name": "Jane Manager"
      },
      "activityable_type": "opportunity",
      "activityable": {
        "id": 890,
        "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
  }
}

Specialized Activity Lists

Today's Activities:

GET /api/v1/crm/activities/today

Upcoming Activities:

GET /api/v1/crm/activities/upcoming?days=7

Overdue Activities:

GET /api/v1/crm/activities/overdue

Viewing Activity Details

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

Query Parameters:

• includes (string) - Relationships to include

Response (200 OK):

{
  "data": {
    "id": 2001,
    "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": 890,
    "activityable": {
      "id": 890,
      "name": "Acme Corp - Enterprise Platform Implementation",
      "value": 150000.00,
      "stage": "proposal"
    },
    "contact_id": 123,
    "contact": {
      "id": 123,
      "name": "John Smith",
      "email": "john@acmecorp.com",
      "phone": "+1-555-0200"
    },
    "assigned_user": {
      "id": 7,
      "name": "Jane Manager",
      "email": "jane@yourcompany.com"
    },
    "created_by": {
      "id": 7,
      "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):

{
  "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):

{
  "message": "Activity updated successfully",
  "data": {
    "id": 2001,
    "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:

{
  "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):

{
  "message": "Activity completed successfully",
  "data": {
    "id": 2001,
    "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:

{
  "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):

{
  "message": "Activity cancelled successfully",
  "data": {
    "id": 2001,
    "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:

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

Response (200 OK):

{
  "message": "Activity rescheduled successfully",
  "data": {
    "id": 2001,
    "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"
  }
}

Activity Productivity

Get Productivity Metrics

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

Query Parameters:

• user_id (integer) - Specific user metrics
• start_date (date) - Period start
• end_date (date) - Period end
• period (string) - Pre-defined period (today, this_week, this_month, this_quarter)

Response (200 OK):

{
  "data": {
    "period": "this_week",
    "start_date": "2025-12-15",
    "end_date": "2025-12-21",
    "metrics": {
      "total_activities": 47,
      "completed_activities": 35,
      "pending_activities": 8,
      "overdue_activities": 4,
      "completion_rate": 74.5,
      "average_completion_time_hours": 1.2,
      "activities_by_type": {
        "call": 18,
        "meeting": 12,
        "email": 10,
        "task": 5,
        "demo": 2
      },
      "activities_by_priority": {
        "high": 12,
        "medium": 28,
        "low": 7
      },
      "billable_hours": 42.5,
      "billable_revenue": 6375.00
    },
    "trends": {
      "vs_last_week": {
        "change_percentage": 12.5,
        "change_count": 5
      }
    },
    "top_performers": [
      {
        "user_id": 7,
        "user_name": "Jane Manager",
        "completed_activities": 35,
        "completion_rate": 89.7
      }
    ]
  }
}

Activity Statistics

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

Response (200 OK):

{
  "data": {
    "overview": {
      "total_activities": 1247,
      "pending": 45,
      "in_progress": 8,
      "completed": 1180,
      "cancelled": 14,
      "overdue": 12
    },
    "this_week": {
      "scheduled": 47,
      "completed": 35,
      "completion_rate": 74.5
    },
    "by_type": {
      "call": 450,
      "meeting": 320,
      "email": 280,
      "task": 150,
      "demo": 47
    },
    "by_priority": {
      "high": 180,
      "medium": 820,
      "low": 247
    },
    "follow_up_required": 23,
    "overdue_by_user": [
      {
        "user_id": 5,
        "user_name": "John Sales",
        "overdue_count": 5
      },
      {
        "user_id": 8,
        "user_name": "Sarah Account",
        "overdue_count": 4
      }
    ]
  }
}

Business Scenarios

Scenario 1: Scheduling Sales Call Series

Context: New opportunity requires multiple touchpoints

Workflow:

# 1. Schedule initial discovery call
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "Initial Discovery Call - Requirements Gathering",
  "activityable_type": "opportunity",
  "activityable_id": 891,
  "assigned_user_id": 7,
  "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": 891,
  "assigned_user_id": 7,
  "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": 891,
  "assigned_user_id": 7,
  "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/2002/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/891
{
  "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:

# 1. Get all overdue activities
GET /api/v1/crm/activities/overdue?assigned_user_id=7

# 2. Prioritize by associated entity value
# High-value opportunity - reschedule immediately
POST /api/v1/crm/activities/2003/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/2004/complete
{
  "outcome": "Task completed. Documentation updated with new customer information.",
  "duration_minutes": 15
}

# 4. Customer unresponsive - cancel and note
POST /api/v1/crm/activities/2005/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/574
{
  "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:

# 1. Complete meeting activity
POST /api/v1/crm/activities/2006/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": 575,
  "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": 575,
  "assigned_user_id": 12,
  "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": 895,
  "contact_id": 145,
  "assigned_user_id": 7,
  "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": 575,
  "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:

# Verify entity exists first
GET /api/v1/crm/opportunities/890
GET /api/v1/crm/customers/568

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

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:

# 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:

# 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": [2010, 2011, 2012],
  "parameters": {
    "reason": "Stale activity, no longer relevant"
  }
}

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

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

Related Documentation

• Lead Management - Tracking lead activities
• Customer Management - Customer interaction history
• Opportunity Pipeline - Opportunity-related activities
• Contact Management - Contact-specific activities