Customers

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

The Customer object

id string

Unique customer identifier (cus_ prefix)

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

ticketCount integer

Total number of tickets

createdAt datetime

When the customer was created

updatedAt datetime

Last modification timestamp

Endpoints

GET List Customers GET Get Customer POST Create Customer PATCH Update Customer DELETE Delete Customer

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

List Customers

Try it

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://www.cstar.help/api/v1/teams/{teamId}/customers?status=active" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Paginated list of customers

{
  "success": true,
  "data": [
    {
      "id": "cus_7c9e667974254de0944be07fc1f90ae7",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "status": "active",
      "sentiment": "positive",
      "ticketCount": 5,
      "createdAt": "2025-11-01T10:00:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z",
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 142,
      "totalPages": 8
    }
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Get Customer

Try it

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

Path Parameters

customerId string required

The customer ID (cus_ prefix)

Code Examples

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

Responses

200 The customer object

{
  "success": true,
  "data": {
    "id": "cus_7c9e667974254de0944be07fc1f90ae7",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "status": "active",
    "sentiment": "positive",
    "tags": [
      "vip",
      "enterprise"
    ],
    "notes": "Key account — escalate issues immediately",
    "ticketCount": 5,
    "createdAt": "2025-11-01T10:00:00Z",
    "updatedAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Customer not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Customer not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Create Customer

Try it

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[]

Array of tag strings. Also accepts comma-separated string via curl.

notes string

Internal notes

metadata object

Arbitrary key-value metadata (max 50 keys). On update, keys are merged — set a key to null to remove it.

Code Examples

curl -X POST "https://www.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

{
  "success": true,
  "data": {
    "id": "cus_7c9e667974254de0944be07fc1f90ae7",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "status": "active",
    "createdAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

400 Validation error

{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": "PARAMETER_MISSING",
    "message": "name and email are required",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

409 Duplicate email

{
  "success": false,
  "error": {
    "type": "conflict_error",
    "code": "CONFLICT",
    "message": "A customer with this email already exists",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Update Customer

Try it

Update one or more fields on an existing customer.

Requires a secret API key.

Path Parameters

customerId string required

The customer ID (cus_ prefix)

Request Body

name string

Full name

email string

Email address

status string

Account status

sentiment string

Override sentiment

tags string[]

Array of tag strings (replaces existing). Also accepts comma-separated string via curl.

notes string

Internal notes

metadata object

Key-value metadata to merge. Existing keys preserved, new keys added. Set a key to null to remove it.

Code Examples

curl -X PATCH "https://www.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

{
  "success": true,
  "data": {
    "id": "cus_7c9e667974254de0944be07fc1f90ae7",
    "name": "Jane Smith",
    "status": "active",
    "updatedAt": "2025-12-10T16:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T16:00:00Z"
  }
}

404 Customer not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Customer not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Delete Customer

Try it

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

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

Path Parameters

customerId string required

The customer ID (cus_ prefix)

Code Examples

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

Responses

200 Customer deleted

{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Customer not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Customer not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}