Complete reference for the Customers API. Manage customer records, tags, and custom fields programmatically.

Customers API Reference

Manage customer records programmatically.

Endpoints

Method Endpoint Description
GET /teams/{teamId}/customers List customers
POST /teams/{teamId}/customers Create customer
GET /teams/{teamId}/customers/{customerId} Get customer
PATCH /teams/{teamId}/customers/{customerId} Update customer
DELETE /teams/{teamId}/customers/{customerId} Delete customer

List Customers

GET /api/v1/teams/{teamId}/customers

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
pageSize integer Items per page (default: 20, max: 100)
status string Filter by status (active, inactive)
sentiment string Filter by sentiment (happy, neutral, frustrated, angry)
search string Search by name or email

Example

curl "https://www.cstar.help/api/v1/teams/{teamId}/customers?status=active" \
  -H "Authorization: Bearer sk_live_xxx"

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "status": "active",
      "sentiment": "happy",
      "tags": ["vip", "enterprise"],
      "ticketCount": 5,
      "notes": "Enterprise customer since 2024",
      "customFields": {
        "company": "Acme Corp",
        "plan": "enterprise"
      },
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-12-14T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

Create Customer

POST /api/v1/teams/{teamId}/customers

Request Body

{
  "name": "John Smith",
  "email": "john@example.com",
  "status": "active",
  "tags": ["trial"],
  "notes": "Signed up via referral",
  "customFields": {
    "company": "Smith Industries",
    "referrer": "Jane Doe"
  }
}

Required Fields

  • name: Customer display name
  • email: Customer email address (must be unique per team)

Optional Fields

  • status: active (default), inactive
  • sentiment: happy, neutral (default), frustrated, angry
  • tags: Array of tag strings
  • notes: Internal notes about the customer
  • customFields: Key-value pairs for custom data

Update Customer

PATCH /api/v1/teams/{teamId}/customers/{customerId}

Request Body

{
  "sentiment": "happy",
  "tags": ["vip", "enterprise"],
  "customFields": {
    "plan": "enterprise"
  }
}

All fields are optional. Only include fields you want to update.

Delete Customer

DELETE /api/v1/teams/{teamId}/customers/{customerId}

Warning: Deleting a customer will also delete all associated tickets.

Webhooks

Customer events trigger webhooks:

  • customer.created - New customer created
  • customer.updated - Customer fields changed

See Webhook Events Reference for payload details.