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: a built-in value or a status your team added. Pending is a widget signup that hasn't confirmed its email yet. cStar makes it active on the first confirmed sign-in. "active" | "inactive" | "churned" | "pending"

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 (built-in values, or a status your team added)

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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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.

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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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 (built-in values, or a status your team added)

sentiment string

Override sentiment

tags string[]

Array of tag strings (replaces existing).

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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

Responses

200 Customer deleted

json

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

404 Customer not found

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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"
  }
}