This API allows you to manage custom fields for customer profiles within a workspace. It enables organisations to tailor customer data collection to their business needs.Introduction#
Customer Profile Fields (CPF) are customisable fields that organisations can define for their customers. This API enables:Defining new custom fields (e.g., "Customer Type", "Loyalty Tier")
Retrieving all fields for a workspace
Updating field definitions
Fetching supported currencies and date formats
Field/Parameter Descriptions#
Customer Profile Field Object
Endpoints#
Endpoints Overview#
| Endpoint | Method | Purpose | Access Control |
|---|
/v1/cpf | PUT | Create a new Custom Profile Field | Authenticated (JWT Token) |
/v1/cpf | POST | Get Custom Profile Fields for a specified workspace | Authenticated (JWT Token) |
/v1/cpf | PATCH | Update Custom Profile Fields | Authenticated (JWT Token) |
/v1/cpf | DELETE | Delete a Custom Profile Field | Authenticated (JWT Token) |
Endpoint:#
Description#
Creates a new custom field for collecting customer profile data within your workspace. This endpoint allows you to define dynamic fields that match your specific customer data collection needs.Purpose#
Enables your application to programmatically create custom fields that will be used for customer data collection, allowing you to tailor the customer profile schema to your business requirements.Business Use Cases#
Dynamic Form Generation: Create fields based on user configuration.
Industry-Specific Fields: Add fields relevant to your specific business vertical (e.g., "Policy Number" for insurance, "Account Type" for banking).
Campaign-Specific Data: Create temporary fields for specific marketing campaigns or data collection initiatives.
Progressive Profiling: Gradually add new fields as your data collection strategy evolves.
Technical Implementation#
Field configuration is sent to NudgeScribe, which:Validates the field type, and
Creates the necessary database schema.
Security Features#
Workspace Isolation: Fields are scoped to your specific workspace.
PII Classification: Mark sensitive fields for automatic encryption and compliance handling.
Input Validation: Field types and formats are validated before creation.
Access Control: Only authenticated users can create fields.
Endpoint:#
Description#
Retrieves all custom fields configured for your workspace, including their definitions, validation rules, and available options for enum fields.Purpose#
Allows your application to dynamically understand the customer data schema and build appropriate user interfaces for data collection and display.Business Use Cases#
Dynamic UI Rendering: Build customer forms based on the current field configuration.
Data Validation Setup: Configure client-side validation based on field requirements.
Export/Import Configuration: Understand data structure for CSV templates or data migration.
Analytics Dashboard: Display customer data fields in reporting interfaces.
Mobile App Synchronisation: Keep mobile applications in sync with the latest field definitions.
Technical Implementation#
Returns complete field metadata including field types, validation rules, required status, and enum options. Your application can use this data to generate forms, validate inputs, and structure customer data properly.Security Features#
Authenticated Access: Only valid JWT Tokens can retrieve field definitions.
Workspace Scoping: Returns only fields accessible to your workspace.
Metadata Only: Returns field structure without actual customer data.
Endpoint:#
Description#
Updates existing custom field properties such as display names, required status, and validation rules while preserving existing customer data.Purpose#
Enables your application to evolve field definitions as business requirements change, maintaining flexibility in your customer data collection strategy.Business Use Case#
Label Updates: Change field display names for better user experience.
Validation Changes: Modify validation rules or required status based on business needs.
Compliance Updates: Update PII classifications for regulatory compliance.
User Experience Optimisation: Reorder fields or adjust properties based on user feedback.
Localisation: Update field names for different markets or languages.
Technical Implementation#
Sends partial updates for specific fields identified by their field_id. The system validates changes and ensures data integrity while applying updates. Protected system fields cannot be modified to maintain platform stability.Security Features#
Change Validation: Prevents modifications that could compromise data integrity.
System Field Protection: Core platform fields are protected from modification.
Audit Logging: All field changes are logged for compliance and debugging.
Incremental Updates: Only specified changes are applied, reducing risk.
Endpoint:#
Description#
Permanently removes custom fields from your workspace, including all associated customer data stored in those fields.Purpose#
Allows cleanup of obsolete fields and supports data minimisation practices for compliance with privacy regulations.Business Use Cases#
Schema Cleanup: Remove fields that are no longer needed for business operations.
Compliance Requirements: Delete fields containing data that should not be retained.
Campaign Completion: Remove temporary fields created for specific campaigns.
Data Minimisation: Reduce data collection to only essential information.
System Maintenance: Clean up test or duplicate fields during system management.
Technical Implementation#
Validates field ownership and workspace access before performing permanent deletion. The operation removes both the field definition and all customer data stored in those fields across your customer base.Security Features#
Irreversible Operation: Includes safeguards to prevent accidental data loss.
Workspace Validation: Ensures you can only delete fields in your own workspace.
Audit Trail: Comprehensive logging of all deletion operations for compliance.
Batch Processing: Efficiently handles multiple field deletions in a single operation.
API Purposes & Use Cases#
Business Customisation: Organisations can define fields relevant to their customer data model.
Compliance: Marking fields as PII helps with privacy and regulatory compliance.
Integration: Client API endpoints allow third-party or frontend apps to manage fields securely.
Business Context#
Enables flexible customer data collection per workspace.
Supports business intelligence by allowing structured, queryable custom fields.
Facilitates compliance with data privacy laws (e.g., GDPR) by flagging PII.
Security & Compliance#
Authentication: All /api endpoints require a valid Bearer token
Authorization: client_api_middleware and dbContext enforce access control.
PII Handling: Fields marked as PII should be handled according to privacy policies.
Audit Logging: All changes to fields should be logged for compliance.
Integration Notes#
Always include Authorization: Bearer <token> for protected endpoints.
All endpoints expect and return JSON.
Common Error Codes#
| Status Code | Description |
|---|
400 | Bad request (missing/invalid fields) |
401 | Unauthorized (invalid/missing token) |
403 | Forbidden (no permission) |
404 | Not found (field or workspace not found) |
500 | Internal server error |
Modified at 2025-10-31 15:07:20
