Customers API

The Customers API allows you to manage your customer data programmatically. Create, retrieve, update, and search customers.

Create a Customer

Add a new customer to your CRM:

POST/api/customers

// Request Body
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "notes": "Interested in business consulting"
}

// Response
{
  "id": "cus_xyz789",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "lead_score": 75,
  "segment": "new_lead",
  "created_at": "2026-06-10T10:30:00Z"
}

List Customers

Retrieve a list of customers with optional filters:

GET/api/customers

// Query Parameters
{
  "segment": "active",
  "search": "jane",
  "page": 1,
  "per_page": 20
}

// Example Response
{
  "data": [
    {
      "id": "cus_xyz789",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "lead_score": 75,
      "segment": "active",
      "created_at": "2026-06-10T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Get a Customer

GET/api/customers/{id}

// Example Response
{
  "id": "cus_xyz789",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "lead_score": 75,
  "engagement_score": 82,
  "ltv": 2450.00,
  "segment": "active",
  "churn_risk": "low",
  "total_bookings": 12,
  "last_booking": "2026-05-20T14:00:00Z",
  "created_at": "2026-01-15T09:00:00Z",
  "tags": ["vip", "repeat"]
}

Update a Customer

PUT/api/customers/{id}

// Request Body
{
  "name": "Jane Smith",  // Updated name
  "phone": "+1987654321",  // Updated phone
  "tags": ["vip", "repeat", "premium"]
}

// Response
{
  "id": "cus_xyz789",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1987654321",
  "tags": ["vip", "repeat", "premium"],
  "updated_at": "2026-06-10T11:00:00Z"
}

Query Parameters

Parameter	Type	Description
segment	string	Filter by segment
search	string	Search by name or email
score_min	integer	Minimum lead score
score_max	integer	Maximum lead score