Skip to main content

Customers

Customers represent the people who submit tickets. Track their history, sentiment, and metadata across all interactions.

The Customer object

id uuid

Unique customer identifier

name string

Full name

email string

Email address

status string

Account status "active" | "inactive"

sentiment string

Calculated sentiment based on interactions "positive" | "neutral" | "negative"

tags string[]

Array of tag strings

notes string

Internal notes about this customer

ticket_count integer

Total number of tickets

created_at datetime

When the customer was created

updated_at datetime

Last modification timestamp

Endpoints

GET List CustomersGET Get CustomerPOST Create CustomerPATCH Update CustomerDELETE Delete Customer
GET /api/v1/teams/{teamId}/customers

List Customers

Retrieve a paginated list of customers with optional filtering.

Query Parameters

status string

Filter by status

sentiment string

Filter by sentiment

search string

Search by name or email

page integer

Page number (1-indexed)

Default: 1

pageSize integer

Results per page (max 100)

Default: 20

Code Examples

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

Responses

200 Paginated list of customers
{
			  "data": [
			    {
			      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			      "name": "Jane Smith",
			      "email": "jane@example.com",
			      "status": "active",
			      "sentiment": "positive",
			      "ticket_count": 5,
			      "created_at": "2025-11-01T10:00:00Z"
			    }
			  ],
			  "pagination": {
			    "page": 1,
			    "pageSize": 20,
			    "total": 142,
			    "totalPages": 8
			  }
			}
401 Authentication failed — missing or invalid API key
{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}
403 Insufficient permissions — wrong key type or team access
{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}
429 Rate limit exceeded
{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}
GET /api/v1/teams/{teamId}/customers/{customerId}

Get Customer

Retrieve a single customer by ID with their full profile and ticket history summary.

Path Parameters

customerId uuid required

The customer ID

Code Examples

curl -X GET "https://app.cstar.help/api/v1/teams/{teamId}/customers/{customerId}" \
			  -H "Authorization: Bearer sk_live_your_key"

Responses

200 The customer object
{
			  "data": {
			    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			    "name": "Jane Smith",
			    "email": "jane@example.com",
			    "status": "active",
			    "sentiment": "positive",
			    "tags": [
			      "vip",
			      "enterprise"
			    ],
			    "notes": "Key account — escalate issues immediately",
			    "ticket_count": 5,
			    "created_at": "2025-11-01T10:00:00Z",
			    "updated_at": "2025-12-10T14:30:00Z"
			  }
			}
404 Customer not found
{
			  "error": {
			    "code": "resource_missing",
			    "message": "Customer not found"
			  }
			}
401 Authentication failed — missing or invalid API key
{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}
403 Insufficient permissions — wrong key type or team access
{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}
429 Rate limit exceeded
{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}
POST /api/v1/teams/{teamId}/customers

Create Customer

Create a new customer record. Email must be unique within your team.

Requires a secret API key.

Request Body

name string required

Full name

email string required

Email address

tags string

Comma-separated tags

notes string

Internal notes

Code Examples

curl -X POST "https://app.cstar.help/api/v1/teams/{teamId}/customers" \
			  -H "Authorization: Bearer sk_live_your_key" \
			  -H "Content-Type: application/json" \
			  -d '{
			    "name": "Jane Smith",
			    "email": "jane@example.com",
			    "tags": "vip,enterprise"
			  }'

Responses

201 Customer created
{
			  "data": {
			    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			    "name": "Jane Smith",
			    "email": "jane@example.com",
			    "status": "active",
			    "created_at": "2025-12-10T14:30:00Z"
			  }
			}
400 Validation error
{
			  "error": {
			    "code": "parameter_missing",
			    "message": "name and email are required"
			  }
			}
409 Duplicate email
{
			  "error": {
			    "code": "conflict",
			    "message": "A customer with this email already exists"
			  }
			}
401 Authentication failed — missing or invalid API key
{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}
403 Insufficient permissions — wrong key type or team access
{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}
429 Rate limit exceeded
{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}
PATCH /api/v1/teams/{teamId}/customers/{customerId}

Update Customer

Update one or more fields on an existing customer.

Requires a secret API key.

Path Parameters

customerId uuid required

The customer ID

Request Body

name string

Full name

email string

Email address

status string

Account status

sentiment string

Override sentiment

tags string

Comma-separated tags (replaces existing)

notes string

Internal notes

Code Examples

curl -X PATCH "https://app.cstar.help/api/v1/teams/{teamId}/customers/{customerId}" \
			  -H "Authorization: Bearer sk_live_your_key" \
			  -H "Content-Type: application/json" \
			  -d '{ "tags": "vip,enterprise,priority" }'

Responses

200 Updated customer
{
			  "data": {
			    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
			    "name": "Jane Smith",
			    "status": "active",
			    "updated_at": "2025-12-10T16:00:00Z"
			  }
			}
404 Customer not found
{
			  "error": {
			    "code": "resource_missing",
			    "message": "Customer not found"
			  }
			}
401 Authentication failed — missing or invalid API key
{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}
403 Insufficient permissions — wrong key type or team access
{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}
429 Rate limit exceeded
{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}
DELETE /api/v1/teams/{teamId}/customers/{customerId}

Delete Customer

Permanently delete a customer. Associated tickets are preserved but unlinked.

Requires a secret API key. This is a destructive operation.

Path Parameters

customerId uuid required

The customer ID

Code Examples

curl -X DELETE "https://app.cstar.help/api/v1/teams/{teamId}/customers/{customerId}" \
			  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Customer deleted
{
			  "data": {
			    "deleted": true
			  }
			}
404 Customer not found
{
			  "error": {
			    "code": "resource_missing",
			    "message": "Customer not found"
			  }
			}
401 Authentication failed — missing or invalid API key
{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}
403 Insufficient permissions — wrong key type or team access
{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}
429 Rate limit exceeded
{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}