Skip to main content

Customer Groups

Customer groups let you organize customers into flexible categories, like Zendesk organizations, Intercom companies, or custom segments. Customers can belong to multiple groups.

The Customer Group object

id string

Unique group identifier

name string

Group name

slug string

URL-friendly slug (auto-generated from name if omitted)

description string

Optional description

externalId string

External platform ID (for import matching, e.g., Zendesk org ID)

customFields object

Arbitrary key-value metadata

customerCount integer

Number of customers in this group

createdAt datetime

When the group was created

updatedAt datetime

Last modification timestamp

Endpoints

GET List Customer GroupsPOST Create Customer GroupGET Get Customer GroupPATCH Update Customer GroupDELETE Delete Customer GroupGET List Group MembersPOST Add Members to GroupDELETE Remove Member from Group
GET /api/v1/teams/{teamId}/customer-groups

List Customer Groups

Retrieve a paginated list of customer groups.

Query Parameters

search string

Search groups by name

page integer

Page number (default: 1)

pageSize integer

Results per page (default: 25, max: 100)

Code Examples

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

Responses

200 List of customer groups
json 
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "object": "customer_group",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "description": "Enterprise tier customer",
      "customerCount": 42,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "pageSize": 25,
    "hasMore": false
  }
}

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}/customer-groups

Create Customer Group

Create a new customer group.

Requires a secret API key.

Request Body

name string required

Group name

slug string

URL-friendly slug (auto-generated if omitted)

description string

Optional description

externalId string

External platform ID for import matching

customFields object

Arbitrary key-value metadata

Code Examples

bash 
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "description": "Enterprise tier"}'

Responses

201 Customer group created
json 
{
  "id": "a1b2c3d4-...",
  "object": "customer_group",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "customerCount": 0,
  "createdAt": "2025-01-15T10:00: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"
  }
}

GET /api/v1/teams/{teamId}/customer-groups/{groupId}

Get Customer Group

Retrieve a single customer group by ID.

Path Parameters

groupId string required

Customer group ID

Code Examples

bash 
curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Customer group details
json 
{
  "id": "a1b2c3d4-...",
  "object": "customer_group",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "description": "Enterprise tier customer",
  "customFields": {
    "tier": "enterprise",
    "region": "us-west"
  },
  "customerCount": 42,
  "createdAt": "2025-01-15T10:00: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}/customer-groups/{groupId}

Update Customer Group

Update a customer group. Only provided fields are changed.

Requires a secret API key.

Path Parameters

groupId string required

Customer group ID

Request Body

name string

Group name

slug string

URL-friendly slug

description string

Description

customFields object

Custom metadata

Code Examples

bash 
curl -X PATCH "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp Updated"}'

Responses

200 Updated customer group
json 
{
  "id": "a1b2c3d4-...",
  "object": "customer_group",
  "name": "Acme Corp Updated"
}

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}/customer-groups/{groupId}

Delete Customer Group

Delete a customer group. Members are removed from the group but not deleted.

Requires a secret API key.

Path Parameters

groupId string required

Customer group ID

Code Examples

bash 
curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Group deleted
json 
{
  "deleted": true,
  "id": "a1b2c3d4-..."
}

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}/customer-groups/{groupId}/members

List Group Members

List customers that belong to a group.

Path Parameters

groupId string required

Customer group ID

Query Parameters

page integer

Page number (default: 1)

pageSize integer

Results per page (default: 25)

Code Examples

bash 
curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}/members" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 List of group members
json 
{
  "data": [
    {
      "id": "cus_xxx",
      "object": "customer",
      "name": "Rick Astley",
      "email": "rick@acme.com",
      "joinedGroupAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "pageSize": 25,
    "hasMore": true
  }
}

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}/customer-groups/{groupId}/members

Add Members to Group

Add one or more customers to a group. Duplicates are silently skipped.

Requires a secret API key.

Path Parameters

groupId string required

Customer group ID

Request Body

customerId string

Single customer ID to add

customerIds string[]

Array of customer IDs to add (max 100). Use this OR customerId.

Code Examples

bash 
curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}/members" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"customerIds": ["cus_xxx", "cus_yyy"]}'

Responses

201 Members added
json 
{
  "added": 3,
  "total": 5,
  "skipped": 2
}

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}/customer-groups/{groupId}/members

Remove Member from Group

Remove a customer from a group.

Requires a secret API key.

Path Parameters

groupId string required

Customer group ID

Query Parameters

customerId string required

Customer ID to remove

Code Examples

bash 
curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/customer-groups/{groupId}/members?customerId=cus_xxx" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Member removed
json 
{
  "removed": true,
  "customerId": "cus_xxx",
  "groupId": "a1b2c3d4-..."
}

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