Customer Management API Documentation

The Customer Management API allows you to manage customer data, track customer metrics, and analyze customer behavior patterns. This API provides comprehensive CRUD operations and advanced analytics for customer relationship management.

Base URL

https://api.talkingshops.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-tenant-api-key: your_api_key_here

API keys are tenant-specific and automatically provide access to the correct customer data for your business.

Rate Limiting

The API implements rate limiting to prevent abuse. By default, each tenant is limited to 100 requests per minute.

Endpoints

Create Customer

POST /customers

Create a new customer record.

Request

{
  "mobile": "919876543210",
  "name": "John Doe",
  "email": "john@example.com",
  "segment": "premium"
}

Parameters

Parameter	Type	Required	Description
mobile	string	Yes	Customer mobile number
name	string	No	Customer full name
email	string	No	Customer email address
segment	string	No	Customer segment/category

Response (201 Created)

{
  "success": true,
  "message": "Customer created successfully",
  "customerId": "64a1b2c3d4e5f6789abc1234"
}

Get Customers

GET /customers

Retrieve a paginated list of customers with optional filtering and search capabilities.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page (1-100, default: 10)
segment	string	Filter by customer segment
startDate	string	Filter by creation date (ISO 8601)
endDate	string	Filter by creation date (ISO 8601)
searchTerm	string	Search in name, mobile, or email
sort	string	Sort field (name, created_at, etc.)

Response (200 OK)

{
  "customers": [
    {
      "_id": "64a1b2c3d4e5f6789abc1234",
      "name": "John Doe",
      "mobile": "919876543210",
      "email": "john@example.com",
      "segment": "premium",
      "created_at": "2023-06-21T14:35:12Z",
      "updated_at": "2023-06-21T14:35:12Z",
      "metrics": {
        "orderCount": 5,
        "lifetimeValue": 1250.50
      }
    }
  ],
  "total": 125,
  "totalPages": 13,
  "activeCount": 120,
  "averageLifetimeValue": 850.75,
  "meta": {
    "hasSegmentation": true,
    "page": 1,
    "limit": 10,
    "sort": "created_at"
  }
}

Get Customer by ID

GET /customers/{customerId}

Retrieve detailed information about a specific customer, including order history and metrics.

Parameters

Parameter	Type	Required	Description
customerId	string	Yes	Unique customer ID

Response (200 OK)

{
  "_id": "64a1b2c3d4e5f6789abc1234",
  "name": "John Doe",
  "mobile": "919876543210",
  "email": "john@example.com",
  "segment": "premium",
  "created_at": "2023-06-21T14:35:12Z",
  "updated_at": "2023-06-21T14:35:12Z",
  "orders": [
    {
      "_id": "64a1b2c3d4e5f6789abc5678",
      "referenceId": "ORD-001",
      "status": "completed",
      "final_amount": 250.00,
      "created_at": "2023-06-20T10:30:00Z"
    }
  ],
  "metrics": {
    "totalOrders": 5,
    "totalSpent": 1250.50,
    "averageOrderValue": 250.10,
    "firstOrderDate": "2023-05-15T08:20:00Z",
    "lastOrderDate": "2023-06-20T10:30:00Z"
  }
}

Get Customer by Mobile

GET /customers/lookup?mobile={mobile}

Look up a customer by their mobile number.

Query Parameters

Parameter	Type	Required	Description
mobile	string	Yes	Customer mobile number

Response (200 OK)

Returns the same customer object as "Get Customer by ID".

Update Customer

PUT /customers/{customerId}

Update customer information.

Parameters

Parameter	Type	Required	Description
customerId	string	Yes	Unique customer ID

Request

{
  "updates": {
    "name": "John Smith",
    "email": "johnsmith@example.com",
    "segment": "vip"
  }
}

Response (200 OK)

{
  "success": true,
  "message": "Customer updated successfully"
}

Delete Customer

DELETE /customers/{customerId}

Delete a customer record.

Parameters

Parameter	Type	Required	Description
customerId	string	Yes	Unique customer ID

Response (200 OK)

{
  "success": true,
  "message": "Customer deleted successfully"
}

Get Customer Statistics

GET /customers/stats

Retrieve comprehensive customer analytics and statistics.

Response (200 OK)

{
  "totalCustomers": 1250,
  "newCustomers": 45,
  "averageOrderValue": 325.50,
  "totalOrders": 5420,
  "revenue": 1763730.00,
  "segmentDistribution": {
    "premium": 125,
    "standard": 890,
    "vip": 235
  },
  "period": {
    "start": "2023-06-01T00:00:00Z",
    "end": "2023-06-30T23:59:59Z"
  }
}

Data Types

Customer Object

Field	Type	Description
_id	string	Unique customer identifier
name	string	Customer full name
mobile	string	Customer mobile number
email	string	Customer email address
segment	string	Customer segment/category
created_at	string	Customer creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

Customer Metrics Object

Field	Type	Description
orderCount	number	Total number of orders
lifetimeValue	number	Total amount spent
totalOrders	number	Total number of orders
totalSpent	number	Total amount spent
averageOrderValue	number	Average value per order
firstOrderDate	string	Date of first order (ISO 8601)
lastOrderDate	string	Date of last order (ISO 8601)

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": {
    "code": "ErrorType",
    "message": "Human-readable error message",
    "details": {
      // Additional error details, if applicable
    }
  }
}

Common Error Codes

Code	Status	Description
AuthenticationError	401	Invalid or missing API key
ValidationError	400	Invalid request parameters
NotFoundError	404	Customer not found
InternalServerError	500	Server error

Best Practices

1. Use pagination: Always implement pagination when fetching customer lists to avoid performance issues.

2. Implement search: Use the searchTerm parameter to provide quick customer lookup functionality.

3. Monitor segments: Use customer segmentation to analyze behavior patterns and target specific groups.

4. Track metrics: Regularly fetch customer metrics to understand customer lifetime value and purchasing patterns.

5. Handle errors gracefully: Implement proper error handling for all API calls.

6. Cache frequently accessed data: Consider caching customer statistics and frequently accessed customer data.

Rate Limiting and Quotas

• Maximum 100 requests per minute per API key
• Customer lookup operations are optimized for frequent use
• Bulk operations may have additional limits

Security Notes

• All customer data is encrypted in transit and at rest
• API keys provide tenant-level isolation
• Customer mobile numbers are used as unique identifiers within each tenant
• Email addresses are validated for format but not verified for deliverability