Customer Management Guide

Overview

Customers are the foundation of your CRM system. Once a lead is converted, they become a customer requiring ongoing relationship management, health monitoring, and growth opportunities. This guide covers comprehensive customer management including creation, segmentation, health scoring, and lifecycle management.

Customer Types

The system supports two primary customer types:

Individual Customers

Type Code: individual
Characteristics: Single person as the customer
Use Cases: B2C businesses, freelancers, consultants, small service businesses
Required Fields: first_name, last_name, email

Business Customers

Type Code: business
Characteristics: Company as the customer entity
Use Cases: B2B businesses, enterprise accounts, corporate clients
Required Fields: company_name, email
Additional: May have multiple contacts (decision makers, users, etc.)

Customer Status

Customers progress through different statuses representing their relationship stage:

Status	Description	Use Case
Active	Current paying customer	Regular purchasing, engaged, using product/service
Inactive	Temporarily not purchasing	No recent activity but relationship maintained
Churned	Former customer no longer active	Stopped purchasing, contract ended
At Risk	Active but showing churn signals	Declining engagement, decreased purchases
Suspended	Account temporarily disabled	Payment issues, policy violations

Customer Segmentation

Segments categorize customers for targeted engagement:

Segment	Criteria	Benefits
Standard	Default segment for new customers	Base level service and support
VIP	High-value, strategic accounts	Premium support, dedicated account manager
Enterprise	Large organizations, high ARR	Custom solutions, strategic partnership
SMB	Small/medium businesses	Standard service, self-service focus
Startup	Early-stage companies	Flexible terms, growth potential

Creating Customers

Create Individual Customer

Endpoint: POST /api/v1/crm/customers

Authentication: Required (Bearer token)

Request Body:

json

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@personal.com",
  "phone": "+1-555-0101",
  "type": "individual",
  "status": "active",
  "industry": "Technology",
  "website": "https://johnsmith.com",
  "billing_address": {
    "street": "456 Oak Avenue",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "USA"
  },
  "shipping_address": {
    "street": "456 Oak Avenue",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "USA"
  },
  "credit_limit": 10000.00,
  "currency": "USD",
  "account_manager_id": 5,
  "tags": ["freelancer", "tech-industry"],
  "notes": "Long-time customer. Prefers email communication.",
  "preferred_communication": "email",
  "timezone": "America/Chicago",
  "language": "en"
}

Response (201 Created):

json

{
  "message": "Customer created successfully",
  "data": {
    "id": 567,
    "customer_number": "CUST-000567",
    "type": "individual",
    "status": "active",
    "segment": "standard",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "email": "john.smith@personal.com",
    "phone": "+1-555-0101",
    "industry": "Technology",
    "currency": "USD",
    "health_score": 0,
    "lifetime_value": 0.00,
    "account_manager_id": 5,
    "created_at": "2025-12-17T16:00:00Z"
  }
}

Create Business Customer

Request Body:

json

{
  "company_name": "Acme Corporation",
  "email": "contact@acmecorp.com",
  "phone": "+1-555-0200",
  "type": "business",
  "status": "active",
  "segment": "enterprise",
  "industry": "Manufacturing",
  "website": "https://acmecorp.com",
  "billing_address": {
    "street": "100 Enterprise Parkway",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "USA"
  },
  "credit_limit": 500000.00,
  "currency": "USD",
  "account_manager_id": 7,
  "lead_id": 1234,
  "tags": ["enterprise", "strategic-account"],
  "custom_fields": {
    "employee_count": "5000+",
    "annual_revenue": "$100M+",
    "parent_company": "Acme Global Holdings"
  },
  "notes": "Converted from lead. Key decision makers: CEO, CFO, CTO."
}

Response (201 Created):

json

{
  "message": "Customer created successfully",
  "data": {
    "id": 568,
    "customer_number": "CUST-000568",
    "type": "business",
    "status": "active",
    "segment": "enterprise",
    "company_name": "Acme Corporation",
    "email": "contact@acmecorp.com",
    "phone": "+1-555-0200",
    "industry": "Manufacturing",
    "credit_limit": 500000.00,
    "currency": "USD",
    "health_score": 0,
    "lifetime_value": 0.00,
    "lead_id": 1234,
    "account_manager_id": 7,
    "created_at": "2025-12-17T16:30:00Z"
  }
}

Listing and Filtering Customers

Get All Customers

Endpoint: GET /api/v1/crm/customers

Query Parameters:

status (string) - Filter by status
segment (string) - Filter by segment
type (string) - Filter by type (individual, business)
account_manager_id (integer) - Filter by account manager
search (string) - Search by name, email, customer number
per_page (integer) - Results per page (default: 25, max: 100)
page (integer) - Page number
sort_by (string) - Sort field (created_at, lifetime_value, health_score)
sort_direction (string) - Sort direction (asc, desc)

Example Request:

bash

GET /api/v1/crm/customers?status=active&segment=vip&sort_by=lifetime_value&sort_direction=desc&per_page=50

Response (200 OK):

json

{
  "data": [
    {
      "id": 568,
      "customer_number": "CUST-000568",
      "type": "business",
      "status": "active",
      "segment": "vip",
      "company_name": "Acme Corporation",
      "email": "contact@acmecorp.com",
      "phone": "+1-555-0200",
      "lifetime_value": 250000.00,
      "total_revenue": 275000.00,
      "health_score": 92,
      "account_manager": {
        "id": 7,
        "name": "Jane Manager",
        "email": "jane@yourcompany.com"
      },
      "created_at": "2025-01-15T10:00:00Z",
      "last_activity_at": "2025-12-17T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 89,
    "last_page": 2
  }
}

Specialized Customer Lists

VIP Customers:

bash

GET /api/v1/crm/customers/vip

At-Risk Customers:

bash

GET /api/v1/crm/customers/at-risk

These endpoints return customers filtered by their respective segments or health scores.

Viewing Customer Details

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

Query Parameters:

includes (string) - Comma-separated relationships: opportunities, orders, activities, lead

Example:

bash

GET /api/v1/crm/customers/568?includes=opportunities,orders,lead

Response (200 OK):

json

{
  "data": {
    "id": 568,
    "customer_number": "CUST-000568",
    "type": "business",
    "status": "active",
    "segment": "enterprise",
    "company_name": "Acme Corporation",
    "email": "contact@acmecorp.com",
    "phone": "+1-555-0200",
    "website": "https://acmecorp.com",
    "industry": "Manufacturing",
    "billing_address": {
      "street": "100 Enterprise Parkway",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "USA"
    },
    "credit_limit": 500000.00,
    "currency": "USD",
    "lifetime_value": 250000.00,
    "total_spent": 275000.00,
    "total_revenue": 275000.00,
    "average_order_value": 25000.00,
    "health_score": 92,
    "acquisition_date": "2025-01-15T10:00:00Z",
    "last_order_date": "2025-12-10T15:30:00Z",
    "last_activity_at": "2025-12-17T14:30:00Z",
    "account_manager": {
      "id": 7,
      "name": "Jane Manager",
      "email": "jane@yourcompany.com"
    },
    "lead": {
      "id": 1234,
      "email": "contact@acmecorp.com",
      "source": "referral",
      "qualified_at": "2025-01-10T12:00:00Z"
    },
    "opportunities": [
      {
        "id": 890,
        "name": "Acme - Platform Expansion",
        "value": 100000.00,
        "stage": "proposal",
        "probability": 75
      }
    ],
    "tags": ["enterprise", "strategic-account"],
    "custom_fields": {
      "employee_count": "5000+",
      "annual_revenue": "$100M+"
    },
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-12-17T14:30:00Z"
  }
}

Updating Customers

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

Request Body (partial update):

json

{
  "phone": "+1-555-0299",
  "segment": "vip",
  "credit_limit": 750000.00,
  "tags": ["enterprise", "strategic-account", "platform-user"],
  "notes": "Upgraded to VIP segment after $250K lifetime value milestone. Increased credit limit.",
  "custom_fields": {
    "employee_count": "7500+",
    "annual_revenue": "$150M+",
    "renewal_date": "2026-01-15"
  }
}

Response (200 OK):

json

{
  "message": "Customer updated successfully",
  "data": {
    "id": 568,
    "segment": "vip",
    "phone": "+1-555-0299",
    "credit_limit": 750000.00,
    "updated_at": "2025-12-17T17:00:00Z"
  }
}

Customer Status Management

Activate Customer

Endpoint: POST /api/v1/crm/customers/{id}/activate

Response (200 OK):

json

{
  "message": "Customer activated successfully",
  "data": {
    "id": 568,
    "status": "active",
    "updated_at": "2025-12-17T17:15:00Z"
  }
}

Deactivate Customer

Endpoint: POST /api/v1/crm/customers/{id}/deactivate

Request Body (optional):

json

{
  "reason": "Customer requested account pause for 3 months",
  "notify": false
}

Response (200 OK):

json

{
  "message": "Customer deactivated successfully",
  "data": {
    "id": 568,
    "status": "inactive",
    "updated_at": "2025-12-17T17:20:00Z"
  }
}

VIP Customer Management

Mark as VIP

Endpoint: POST /api/v1/crm/customers/{id}/mark-vip

Request Body:

json

{
  "reason": "Exceeded $250K lifetime value threshold",
  "benefits": ["Dedicated account manager", "Priority support", "Custom pricing"],
  "notify_account_manager": true
}

Response (200 OK):

json

{
  "message": "Customer marked as VIP successfully",
  "data": {
    "id": 568,
    "segment": "vip",
    "updated_at": "2025-12-17T17:30:00Z"
  }
}

Remove VIP Status

Endpoint: DELETE /api/v1/crm/customers/{id}/mark-vip

Request Body:

json

{
  "reason": "Lifetime value dropped below threshold due to refunds"
}

Response (200 OK):

json

{
  "message": "VIP status removed successfully",
  "data": {
    "id": 568,
    "segment": "standard",
    "updated_at": "2025-12-17T17:35:00Z"
  }
}

Customer Activities

Get Customer Activities

Endpoint: GET /api/v1/crm/customers/{customerId}/activities

Query Parameters:

type (string) - Filter by activity type
from_date (date) - Start date
to_date (date) - End date
per_page (integer) - Results per page

Response (200 OK):

json

{
  "data": [
    {
      "id": 1001,
      "type": "call",
      "subject": "Quarterly Business Review",
      "description": "Discussed usage metrics, upcoming features, and renewal.",
      "status": "completed",
      "scheduled_at": "2025-12-15T14:00:00Z",
      "completed_at": "2025-12-15T15:00:00Z",
      "assigned_user": {
        "id": 7,
        "name": "Jane Manager"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 45
  }
}

Get Customer Statistics

Endpoint: GET /api/v1/crm/customers/{id}/stats

Response (200 OK):

json

{
  "data": {
    "customer_id": 568,
    "lifetime_metrics": {
      "lifetime_value": 250000.00,
      "total_spent": 275000.00,
      "total_revenue": 275000.00,
      "average_order_value": 25000.00,
      "order_count": 11,
      "first_order_date": "2025-01-20T10:00:00Z",
      "last_order_date": "2025-12-10T15:30:00Z"
    },
    "engagement_metrics": {
      "health_score": 92,
      "last_activity_at": "2025-12-17T14:30:00Z",
      "days_since_last_activity": 0,
      "total_activities": 45,
      "activity_frequency": "high"
    },
    "opportunity_metrics": {
      "open_opportunities": 2,
      "total_opportunity_value": 175000.00,
      "opportunities_won": 8,
      "opportunities_lost": 1,
      "win_rate": 88.89
    },
    "support_metrics": {
      "open_tickets": 1,
      "average_response_time": "2 hours",
      "satisfaction_score": 4.8
    }
  }
}

Bulk Operations

Endpoint: POST /api/v1/crm/customers/bulk-actions

Supported Actions:

assign - Assign customers to account manager
update_segment - Change customer segment
add_tags - Add tags to multiple customers
remove_tags - Remove tags
export - Export customer data

Example - Assign Account Manager:

json

{
  "action": "assign",
  "customer_ids": [568, 569, 570],
  "parameters": {
    "account_manager_id": 7
  }
}

Response (200 OK):

json

{
  "message": "Bulk action completed successfully",
  "data": {
    "action": "assign",
    "processed": 3,
    "successful": 3,
    "failed": 0
  }
}

Business Scenarios

Scenario 1: New Customer Onboarding

Context: Converting a lead to customer and setting up their account

Workflow:

Lead converted to customer
Assign account manager
Set up payment terms and credit limit
Create initial opportunity
Schedule onboarding call

API Calls:

bash

# Customer already created via lead conversion
# GET customer details
GET /api/v1/crm/customers/568

# Update with account details
PATCH /api/v1/crm/customers/568
{
  "account_manager_id": 7,
  "credit_limit": 50000.00,
  "payment_terms": {
    "net_days": 30,
    "discount": "2% 10 Net 30"
  },
  "tags": ["new-customer", "onboarding"]
}

# Create onboarding activity
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "Customer Onboarding Call",
  "customer_id": 568,
  "scheduled_at": "2025-12-20T10:00:00Z",
  "assigned_user_id": 7
}

Scenario 2: VIP Upgrade

Context: Customer crosses $250K lifetime value threshold

Workflow:

System or manual detection of milestone
Update segment to VIP
Assign dedicated account manager
Notify customer of VIP benefits
Schedule strategic planning session

API Calls:

bash

# Mark as VIP
POST /api/v1/crm/customers/568/mark-vip
{
  "reason": "Exceeded $250K lifetime value milestone",
  "benefits": ["Dedicated account manager", "Priority support", "Quarterly business reviews"],
  "notify_account_manager": true
}

# Update credit limit
PATCH /api/v1/crm/customers/568
{
  "credit_limit": 500000.00,
  "notes": "Upgraded to VIP. Increased credit limit. Assigned dedicated AM."
}

# Schedule QBR
POST /api/v1/crm/activities
{
  "type": "meeting",
  "subject": "VIP Onboarding - Quarterly Business Review",
  "customer_id": 568,
  "scheduled_at": "2025-12-22T14:00:00Z",
  "assigned_user_id": 7
}

Scenario 3: Churn Prevention

Context: Customer shows declining engagement and health score

Workflow:

System detects declining health score
Mark customer as "at risk"
Assign customer success manager
Schedule urgent check-in call
Create retention opportunity

API Calls:

bash

# Update status to at-risk
PATCH /api/v1/crm/customers/569
{
  "status": "at_risk",
  "tags": ["at-risk", "churn-prevention"],
  "notes": "Health score dropped from 85 to 55 over 30 days. No activity in 20 days. Last purchase 45 days ago."
}

# Create urgent activity
POST /api/v1/crm/activities
{
  "type": "call",
  "subject": "URGENT: Customer Check-in - Churn Risk",
  "customer_id": 569,
  "priority": "high",
  "scheduled_at": "2025-12-18T09:00:00Z",
  "assigned_user_id": 7,
  "notes": "Address declining engagement. Understand if they're experiencing issues or considering alternatives."
}

Best Practices

1. Maintain Complete Profiles

Essential Information:

Contact details (email, phone)
Billing/shipping addresses
Communication preferences
Industry and company size
Decision makers and stakeholders

2. Regular Health Score Monitoring

Monitor:

Purchase frequency
Engagement levels
Support interactions
Product usage metrics
Payment history

Act On:

Health score below 60: Immediate attention
Health score 60-75: Proactive check-in
Health score 75-85: Regular monitoring
Health score 85+: Expansion opportunities

3. Segment Appropriately

Review Quarterly:

Lifetime value changes
Engagement patterns
Strategic importance
Growth potential
Support requirements

4. Document Everything

Track:

All interactions (calls, emails, meetings)
Decisions made
Commitments given
Issues raised
Feedback provided

Integration Points

With Sales Module

Orders linked to customers
Revenue tracking automatic
Payment history maintained

With Opportunity Module

Upsell/cross-sell opportunities tracked
Pipeline value per customer calculated
Win/loss analysis by customer type

With Support Module

Support tickets linked to customers
Resolution time tracked
Satisfaction scores recorded

Lead Conversion Guide - Converting leads to customers
Customer Health Scoring - Monitoring customer health
Opportunity Pipeline - Managing opportunities
Activity Management - Tracking interactions

Customer Management Guide ​

Overview ​

Customer Types ​

Individual Customers ​

Business Customers ​

Customer Status ​

Customer Segmentation ​

Creating Customers ​

Create Individual Customer ​

Create Business Customer ​

Listing and Filtering Customers ​

Get All Customers ​

Specialized Customer Lists ​

Viewing Customer Details ​

Updating Customers ​

Customer Status Management ​

Activate Customer ​

Deactivate Customer ​

VIP Customer Management ​

Mark as VIP ​

Remove VIP Status ​

Customer Activities ​

Get Customer Activities ​

Get Customer Statistics ​

Bulk Operations ​

Business Scenarios ​

Scenario 1: New Customer Onboarding ​

Scenario 2: VIP Upgrade ​

Scenario 3: Churn Prevention ​

Best Practices ​

1. Maintain Complete Profiles ​

2. Regular Health Score Monitoring ​

3. Segment Appropriately ​

4. Document Everything ​

Integration Points ​

With Sales Module ​

With Opportunity Module ​

With Support Module ​

Related Documentation ​

Customer Management Guide

Overview

Customer Types

Individual Customers

Business Customers

Customer Status

Customer Segmentation

Creating Customers

Create Individual Customer

Create Business Customer

Listing and Filtering Customers

Get All Customers

Specialized Customer Lists

Viewing Customer Details

Updating Customers

Customer Status Management

Activate Customer

Deactivate Customer

VIP Customer Management

Mark as VIP

Remove VIP Status

Customer Activities

Get Customer Activities

Get Customer Statistics

Bulk Operations

Business Scenarios

Scenario 1: New Customer Onboarding

Scenario 2: VIP Upgrade

Scenario 3: Churn Prevention

Best Practices

1. Maintain Complete Profiles

2. Regular Health Score Monitoring

3. Segment Appropriately

4. Document Everything

Integration Points

With Sales Module

With Opportunity Module

With Support Module

Related Documentation