This API provides comprehensive customer data management capabilities, including upload, retrieval, update, and deletion of customer records with encrypted profile data and CSV bulk operations.

Introduction

The Customer Management API enables organisations to manage customer data with enterprise-grade security features:

Bulk CSV Upload: Import thousands of customers via CSV files

Encrypted PII Storage: Sensitive data is encrypted using account-specific keys

Custom Profile Fields: Store dynamic customer attributes based on workspace configuration

Async Processing: Large uploads are queued for background processing

Data Validation: Comprehensive field validation against workspace schema

These endpoints are designed for CRM systems, marketing platforms, and customer data platforms requiring secure, scalable customer data management.

Field Descriptions

Customers

Endpoints

Endpoints Overview

Endpoint	Method	Purpose	Access Control
`/v1/customer/check`	POST	Upload and Validate new customers	Authenticated (JWT Token)
`/v1/customer/pages`	POST	LOREM	Authenticated (JWT Token)
`/v1/customer`	POST	Retrieve customers by group	Authenticated (JWT Token)
`/v1/customer`	PATCH	Update existing customers	Authenticated (JWT Token)
`/v1/customer`	DELETE	Delete customers	Authenticated (JWT Token)

1. Upload and Validate Customer Data

Endpoint:

POST /v1/customer/check

Pick either the Data File or the Customer data object in the Request Body.

Description

Securely uploads new customer records to your workspace with automatic encryption of sensitive data and background processing for large datasets.

Purpose

Enables bulk customer data import with enterprise-grade security, ensuring sensitive information is properly encrypted and stored according to your field configurations.

Business Use Cases

Customer Onboarding: Import customer lists from CRM systems, spreadsheets, or other platforms.

Data Migration: Transfer customer data when switching systems or consolidating databases.

Marketing Campaign Setup: Upload prospect lists for targeted campaigns.

Event Registration: Process bulk registrations from events or sign-up forms.

Partner Data Integration: Import customer data from business partners or third-party sources.

Technical Implementation

Submit customer data via CSV or individual customer objects. The system automatically encrypts sensitive fields marked as PII, validates all data against your field schema, and processes uploads asynchronously for optimal performance.

Security Features

Automatic PII Encryption: Sensitive fields are encrypted using your account's unique encryption keys.

Asynchronous Processing: Large uploads are queued to prevent system overload.

Data Validation: All customer data is validated before storage.

Job Tracking: Receive job IDs to monitor upload progress and status.

2. Get Customer Page Count

Endpoint:

POST /v1/customer/pages

Description

Returns the total number of pages available for a customer group, enabling efficient pagination when retrieving large customer datasets.

Purpose

Allows your application to implement proper pagination controls and manage memory efficiently when displaying large customer lists.

Business Use Cases

UI Pagination: Build pagination controls in your customer management interface

Performance Planning: Understand the dataset size before implementing data retrieval

Memory Management: Plan data loading strategies for large customer groups

User Experience: Provide progress indicators and navigation for large lists

Export Planning: Determine batch sizes for data export operations

Technical Implementation

Provide a customer group ID to receive the total page count based on standard page sizes (1000 customers per page). Use this information to build pagination logic in your application.

Security Features

Access Control: Only returns page counts for customer groups you have access to

Workspace Isolation: Page counts are scoped to your specific workspace

Efficient Queries: Uses optimised database queries that don't load actual customer data

3. Get Customers

Endpoint:

POST /v1/customer

The page numbers field in the request body uses array indexing.
Pages: 5
Page numbers: 0 - 4

Description

Retrieves customer records from a specific customer group with pagination support, returning encrypted profile data that can be decrypted as needed.

Purpose

Enables your application to fetch and display customer data with proper pagination and security controls.

Business Use Cases

Customer Management Interface: Display customer lists in your CRM or admin interface.

Campaign Targeting: Retrieve specific customer segments for marketing campaigns.

Data Analysis: Export customer data for reporting and analytics.

Customer Service: Access customer information for support operations.

Compliance Reporting: Extract customer data for regulatory or audit purposes.

Technical Implementation

Specify the customer group and page number to retrieve up to 1000 customers per request. Customer profile data is returned with sensitive fields encrypted - use your account's decryption key to access PII when needed.

Security Features

Encrypted PII: Sensitive customer data remains encrypted in transit and storage.

Pagination Limits: Reasonable page sizes prevent memory exhaustion.

Access Control: Only returns customers from groups you have permission to access.

Audit Logging: All data access is logged for compliance and security monitoring.

4. Update Customers

Endpoint:

PATCH /v1/customer

Pick either the Data File or the Customer data object in the Request Body.

Description

Updates existing customer records by matching unique identifiers, with support for both bulk CSV updates and individual customer modifications.

Purpose

Enables your application to keep customer data current by updating records as information changes, while maintaining data security and integrity.

Business Use Cases

Profile Updates: Update customer information as it changes over time.

Data Enrichment: Add new attributes or update existing customer profiles.

Campaign Response Tracking: Update customer status based on campaign interactions.

Data Correction: Fix data quality issues or correct customer information.

Progressive Profiling: Gradually collect additional customer information over time.

Technical Implementation

Provide updated customer data with unique identifiers to match existing records. The system re-encrypts sensitive fields with fresh encryption while preserving data integrity and relationships.

Security Features

Unique ID Matching: Secure identification of customers to prevent accidental updates.

Fresh Encryption: PII fields are re-encrypted with new encryption parameters.

Asynchronous Processing: Large update operations are queued for optimal performance.

Change Auditing: All customer updates are logged with user identification.

5. Delete Customers

Endpoint:

DELETE /v1/customer

Description

Permanently removes customer records from your workspace, supporting both individual and bulk deletion operations with comprehensive audit logging.

Purpose

Enables secure customer data deletion for compliance with privacy regulations, data retention policies, or customer requests.

Business Use Cases

Privacy Compliance: Honour customer requests for data deletion (Right to be Forgotten).

Data Retention: Remove customer records according to your retention policies.

Data Quality: Clean up duplicate, test, or invalid customer records.

Campaign Cleanup: Remove customers from completed or cancelled campaigns.

Opt-out Processing: Handle customer requests to be removed from your database.

Technical Implementation

Specify customer group and customer IDs for deletion. The operation is permanent and immediately removes all customer data, including encrypted profile information.

Security Features

Permanent Deletion: Complete removal of customer data with no recovery option.

Batch Operations: Efficient bulk deletion with transaction safety.

Access Validation: Confirms you have permission to delete specified customers.

Comprehensive Auditing: All deletions logged with user ID and timestamp for compliance.

Data Processing & Encryption

Extended Profile Structure

The extended_profile field contains dynamic customer attributes based on workspace configuration.

Example:

{
  "email": "encrypted-base64-string",  // PII field (encrypted)
  "phone": "encrypted-base64-string",  // PII field (encrypted) 
  "first_name": "John",               // Non-PII field (plain text)
  "last_name": "Doe",                 // Non-PII field (plain text)
  "customer_type": "VIP",             // Enum field (plain text)
  "signup_date": "2023-08-20",        // Date field (plain text)
  "lifetime_value": 1500.00           // Currency field (plain text)
}

Encryption Process

Field Classification: Fields marked as PII in the workspace configuration are encrypted

Account Key Retrieval: Each account has a unique encryption key

AES-GCM Encryption: PII fields encrypted with IV and auth tag

Base64 Encoding: Encrypted data stored as base64 strings

Field Sorting: All fields alphabetically sorted for consistency

Data Validation

Type Validation: String, Number, Boolean, Date fields validated

Enum Validation: Values must match predefined options

Required Field Check: Mandatory fields must have values

Format Validation: Date and currency formats validated

Regex Validation: Custom regex patterns applied where defined

Async Processing

Job Queue System

Large operations are processed asynchronously using Bull queue:

Upload Jobs: Customer creation queued for batch processing

Update Jobs: Customer updates are queued to prevent blocking

Job IDs: Unique identifiers for tracking job status

Retry Logic: Failed jobs retry with exponential backoff

Progress Tracking: Job progress can be monitored

Job ID Format

{hostname}/{account_id}/{operation}_customers/{random_uuid}

Performance Limits

CSV Size Limit: 10,000 rows maximum per upload

Batch Processing: Large datasets split into manageable chunks

Memory Management: Streaming CSV parsing for large files

Concurrent Jobs: Multiple jobs can run simultaneously per account

Security & Compliance

Data Protection

Account-Level Encryption: Each organisation has unique encryption keys

PII Identification: Fields marked as PII are automatically encrypted

Key Storage: Encryption keys stored securely and encoded

Data Isolation: Account-level data access control enforced

Access Control

Authentication Required: All endpoints require valid JWT tokens

Account Isolation: Users can only access their account's customers

Database Context: All operations use an authenticated database context

Permission Validation: User permissions verified before operations

Audit & Compliance

Operation Logging: All customer operations logged with the user ID

Timestamp Tracking: Creation and modification times recorded

Deletion Logging: Customer deletions are specifically logged as warnings

Job Tracking: Async operations tracked with unique job IDs

Data Retention

Permanent Deletion: Delete operations are irreversible

Backup Recommendations: Regular backups are recommended before bulk operations

Compliance Support: Supports GDPR right to be forgotten

Data Minimisation: Only necessary data is stored and processed

Common Error Codes

Status Code	Description	Common Causes
`400`	Bad Request	Missing fields, invalid CSV format, data validation failures
`401`	Unauthorized	No customers found, invalid customer group
`403`	Forbidden	Missing authentication, no database context
`500`	Internal Server Error	Database errors, encryption failures, queue errors

Specific Error Messages

"missing required fields": Required request body fields not provided

"missing valid workspace": Workspace has no custom fields defined

"File cannot be larger than 10000 rows": CSV exceeds size limit

"Data is clean to upload": Validation passed successfully

"No customers found": Customer group contains no records

Customer Management

Introduction#

Field Descriptions#

Endpoints#

Endpoints Overview#

1. Upload and Validate Customer Data#

Endpoint:#

Description#

Purpose#

Business Use Cases#

Technical Implementation#

Security Features#

2. Get Customer Page Count#

Endpoint:#

Description#

Purpose#

Business Use Cases#

Technical Implementation#

Security Features#

3. Get Customers#

Endpoint:#

Description#

Purpose#

Business Use Cases#

Technical Implementation#

Security Features#

4. Update Customers#

Endpoint:#

Description#

Purpose#

Business Use Cases#

Technical Implementation#

Security Features#

5. Delete Customers#

Endpoint:#

Description#

Purpose#

Business Use Cases#

Technical Implementation#

Security Features#

Data Processing & Encryption#

Extended Profile Structure#

Example:#

Encryption Process#

Data Validation#

Async Processing#

Job Queue System#

Job ID Format#

Performance Limits#

Security & Compliance#

Data Protection#

Access Control#

Audit & Compliance#

Data Retention#

Common Error Codes#

Specific Error Messages#

Introduction

Field Descriptions

Endpoints

Endpoints Overview

1. Upload and Validate Customer Data

Endpoint:

Description

Purpose

Business Use Cases

Technical Implementation

Security Features

2. Get Customer Page Count

Endpoint:

Description

Purpose

Business Use Cases

Technical Implementation

Security Features

3. Get Customers

Endpoint:

Description

Purpose

Business Use Cases

Technical Implementation

Security Features

4. Update Customers

Endpoint:

Description

Purpose

Business Use Cases

Technical Implementation

Security Features

5. Delete Customers

Endpoint:

Description

Purpose

Business Use Cases

Technical Implementation

Security Features

Data Processing & Encryption

Extended Profile Structure

Example:

Encryption Process

Data Validation

Async Processing

Job Queue System

Job ID Format

Performance Limits

Security & Compliance

Data Protection

Access Control

Audit & Compliance

Data Retention

Common Error Codes

Specific Error Messages