This API provides comprehensive management of customer groups within workspaces, enabling organisations to segment and organise their customer base for targeted campaigns, analytics, and data management.
Introduction#
The Customer Groups API enables organisations to create logical segments of their customer base:Customer Segmentation: Group customers by demographics, behaviour, or business criteria
Campaign Management: Organise customers for marketing campaigns and communications
Data Organisation: Structure customer data for analytics and reporting
Access Control: Manage customer data access at the group level
Field Descriptions#
Endpoints#
Endpoints Overview#
| Endpoint | Method | Purpose | Access Control |
|---|
/v1/cg | PUT | Create a new customer group | Authenticated (JWT Token) |
/v1/cg | POST | Retrieve customer groups | Authenticated (JWT Token) |
/v1/cg | PATCH | Update a customer group | Authenticated (JWT Token) |
/v1/cg | DELETE | Delete a customer group | Authenticated (JWT Token) |
Endpoint:#
Description#
Creates a new customer group within your workspace, enabling you to organise customers into logical segments for targeted campaigns, analytics, and data management.Purpose#
Allows your application to programmatically create customer segments that can be used to organise customers based on business criteria, demographics, behaviour, or any other segmentation strategy.Business Use Cases#
Marketing Segmentation: Create groups like "High-Value Customers", "New Prospects", "VIP Members" for targeted campaigns.
Geographic Organisation: Segment customers by region, country, or sales territory.
Behavioural Grouping: Create segments based on purchase behaviour, engagement levels, or lifecycle stages.
Campaign Management: Organise customers for specific email campaigns, promotions, or surveys.
A/B Testing: Create test and control groups for marketing experiments.
Product Lines: Group customers by product interest or subscription tiers.
Technical Implementation#
Your application sends the workspace ID and group name to create a new customer segment. The system generates a unique group ID and associates it with your workspace. Once created, customers can be assigned to this group for organised data management.Security Features#
Workspace Isolation: Groups are securely scoped to your specific workspace
Authenticated Access: Only authenticated API clients can create customer groups
Input Validation: Group names and workspace IDs are validated before creation
Audit Logging: All group creation activities are logged for compliance tracking
Endpoint:#
Description#
Retrieves all customer groups within your workspace, providing complete information about your customer segmentation structure.Purpose#
Enables your application to understand and display the current customer segmentation setup, supporting UI elements like dropdowns, analytics dashboards, and customer assignment interfaces.Business Use Cases#
Group Selection: Populate dropdown menus for customer assignment or campaign targeting.
Analytics Dashboards: Display group metrics and customer distribution across segments.
Campaign Setup: Show available target audiences when creating marketing campaigns.
Data Export: List groups for reporting and data analysis purposes.
Administrative Views: Provide an overview of customer segmentation for management.
Mobile App Sync: Keep mobile applications updated with the current group structure.
Technical Implementation#
Send your workspace ID to receive a complete list of customer groups with their names, IDs, and metadata. This data can be cached in your application and refreshed periodically to maintain current segmentation information.Security Features#
Workspace-Scoped Access: Only returns groups that belong to your workspace
Authentication Required: Valid API credentials are required to access group information
No Customer Data Exposure: Returns group metadata without actual customer information
Efficient Queries: Optimised data retrieval that doesn't impact system performance
Endpoint:#
Description#
Updates the name and properties of an existing customer group while preserving all customer assignments and historical data associated with the group.Purpose#
Allows your application to evolve group names and properties as business needs change, maintaining flexibility in your customer segmentation strategy.Business Use Cases#
Rebranding: Update group names to reflect new business terminology or marketing strategies.
Clarity Improvement: Rename groups for better understanding and organisation.
Campaign Evolution: Modify group names based on campaign performance or strategic changes.
Standardisation: Align group names with company naming conventions.
Localisation: Update names for different markets or regional preferences.
User Experience: Improve group names based on user feedback and usability testing.
Technical Implementation#
Provide the workspace ID, group ID, and new group name to update an existing customer group. The system validates ownership and applies the changes while preserving all customer relationships and historical associations.Security Features#
Ownership Validation: Confirms you have permission to modify the specified group.
Workspace Boundary: Ensures updates only affect groups within your workspace.
Data Integrity: Preserves all customer assignments and relationships during updates.
Change Auditing: All group modifications are logged with user identification.
Endpoint:#
Description#
Permanently removes a customer group from your workspace. This operation should be used carefully as it may affect customer organisation and reporting capabilities.Purpose#
Enables cleanup of obsolete or unused customer groups, helping maintain a clean and organised segmentation structure in your workspace.Business Use Cases#
Campaign Cleanup: Remove groups created for completed or cancelled campaigns.
Data Hygiene: Clean up test groups or duplicate segments.
Workspace Maintenance: Remove obsolete groups during system reorganisation.
Simplification: Reduce segmentation complexity by removing unused groups.
Compliance: Delete groups as part of data retention and privacy policies.
Migration Cleanup: Remove temporary groups created during data migration processes.
Technical Implementation#
Specify the workspace ID and group ID to permanently delete a customer group. The operation immediately removes the group from your workspace. Consider the impact on customers currently assigned to this group before deletion.Security Features#
Permanent Operation: Irreversible deletion with comprehensive audit logging.
Access Control: Validates workspace ownership before allowing deletion.
Impact Assessment: System considerations for customers currently in the group.
Audit Trail: Complete logging of deletion operations with user identification.
Data Impact: Deleting a group may affect associated customer records
Cascade Effects: Consider impact on campaigns, reports, or other features using this group
Irreversible: Group deletion cannot be undone
Audit Trail: All deletions are logged with user identification
Business Context#
Customer Segmentation Strategy#
Customer groups enable businesses to:Target Marketing: Create focused campaigns for specific customer segments
Personalisation: Deliver tailored experiences based on group characteristics
Performance Tracking: Measure success across different customer segments
Resource Allocation: Optimise resources based on group value and potential
Data Organisation Benefits#
Simplified Management: Easier to handle large customer bases through logical grouping
Improved Analytics: Better insights through segment-based analysis
Operational Efficiency: Streamlined processes for group-based operations
Compliance Support: Easier data management for regulatory requirements
Security & Compliance#
Access Control#
Authentication Required: All endpoints require valid JWT tokens
Workspace Isolation: Users can only access groups within their authorized workspaces
Database Context: All operations use authenticated database context
Operation Validation: User permissions verified before any modifications
Data Protection#
Workspace Boundaries: Strict enforcement of workspace-level access control
Audit Logging: All group operations logged with user identification
Input Validation: All inputs validated to prevent injection attacks
Error Handling: Secure error messages that don't expose sensitive information
Audit & Compliance#
Operation Logging: All CRUD operations logged with timestamps and user IDs
Deletion Tracking: Group deletions specifically logged as warnings
Change History: Timestamps track when groups are created and modified
User Attribution: All changes attributed to specific authenticated users
Common Error Codes#
| Status Code | Description | Common Causes |
|---|
400 | Bad Request | Missing required fields, invalid UUID format |
401 | Unauthorized | Group not found, invalid customer group ID |
403 | Forbidden | Missing authentication, no database context |
500 | Internal Server Error | Database connection issues, server errors |
Modified at 2025-10-31 15:04:58
