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
To create or update a Custom Profile Field, the field_type and field_format fields are used. They each have a set of values they accept.Field Types#
There are 5 field types to choose from. Here is a list of the different field_type values you can use.| Name | Value | Requires field_format |
|---|
| String | "string" | ✖️ |
| Number | "number" | ✖️ |
| Charater | "char" | ✖️ |
| Date | "Date" | ✅ |
| Currency | "currency" | ✅ |
For the field_format field there are a couple of options available depending on the field_type.| Name | Format |
|---|
| ISO 8601 (global, APIs, DBs) | "yyyy-MM-dd" |
| Day/Month/Year (Europe, Africa, Asia, LatAm) | "dd/MM/yyyy" |
| Month/Day/Year (US, Philippines) | "MM/dd/yyyy" |
| Day-Month-Year (Europe, India) | "dd-MM-yyyy" |
| Month-Day-Year (US alt) | "MM-dd-yyyy" |
| Day.Month.Year (Central/Eastern Europe, Russia) | "dd.MM.yyyy" |
| Year/Month/Day (Japan, China, Korea) | "yyyy/MM/dd" |
| Day ShortMonth Year (UK, Intl business) | "dd MMM yyyy" |
| ShortMonth Day, Year (US formal) | "MMM dd, yyyy" |
| FullMonth Day, Year (US/Intl long form) | "MMMM dd, yyyy" |
| Day FullMonth Year (Europe, formal docs) | "dd MMMM yyyy" |
| Year/Month/Day short (Japan short form) | "yy/MM/dd" |
| Day/Month/Year short (Europe shorthand) | "dd/MM/yy" |
| Month/Day/Year short (US shorthand) | "MM/dd/yy" |
Currency Types:
"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD""BDT""BGN""BHD""BIF""BMD""BND""BOB""BOV""BRL""BSD""BTN""BWP""BYN""BZD""CAD""CDF""CHE""CHF""CHW""CLF""CLP""CNY""COP""COU""CRC""CUC""CUP""CVE""CZK""DJF""DKK""DOP""DZD""EGP""ERN""ETB""EUR""FJD""FKP""GBP""GEL""GHS""GIP""GMD""GNF""GTQ""GYD""HKD""HNL""HTG""HUF""IDR""ILS""INR""IQD""IRR""ISK""JMD""JOD""JPY""KES""KGS""KHR""KMF""KPW""KRW""KWD""KYD""KZT""LAK""LBP""LKR""LRD""LSL""LYD""MAD""MDL""MGA""MKD""MMK""MNT""MOP""MRU""MUR""MVR""MWK""MXN""MXV""MYR""MZN""NAD""NGN""NIO""NOK""NPR""NZD""OMR""PAB""PEN""PGK""PHP""PKR""PLN""PYG""QAR""RON""RSD""RUB""RWF""SAR""SBD""SCR""SDG""SEK""SGD""SHP""SLE""SOS""SRD""SSP""STN""SVC""SYP""SZL""THB""TJS""TMT""TND""TOP""TRY""TTD""TWD""TZS""UAH""UGX""USD""USN""UYI""UYU""UYW""UZS""VED""VES""VND""VUV""WST""XAF""XAG""XAU""XBA""XBB""XBC""XBD""XCD""XDR""XOF""XPD""XPF""XPT""XSU""XTS""XUA""XXX""YER""ZAR""ZMW""ZWG"String, Number, and Char Types:
There is no formatting required for these fields. Simply pass null as the field_format value.
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 and validation rules.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, and required status. 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 2026-01-28 17:40:43
