Custom attributes: Extensibility guide

This guide details the Custom Attributes framework in Zenskar. This system allows you to extend the standard data model for Customers, Contracts, and Products, ensuring the platform adapts to your specific business logic, reporting requirements, and third-party integrations.

1. Core concepts: The data extensibility framework

Custom Attributes (also referred to as Custom Fields or Metafields) are the primary mechanism for adding bespoke data points to Zenskar’s core objects.

Why use custom attributes?

Standard SaaS schemas often lack the granularity required for complex B2B operations. Custom attributes solve this by providing:

• Structural integrity: Unlike free-text "Notes" fields, custom attributes use defined data types (integer, boolean, etc.) to ensure data consistency across thousands of records.
• Downstream automation: Attributes are assigned a permanent Property Key Name. This key acts as the technical anchor for API integrations and Webhooks to pass data to external systems like your CRM or ERP.
• Governance: Admin-defined rules, such as the Mandatory Field toggle, ensure that your team captures critical information every time a new record is created.

Supported objects

Custom attributes can be independently configured for each of the following core objects:

2. Quickstart guide: Setting up custom attributes

This quickstart covers adding a custom field to any of the three supported objects.

1. Navigate to Settings: Go to Settings > Custom Attributes.

2. Select object: Scroll to the object you wish to extend (Customer, Contract, or Product).

3. Add Property: Click the + ADD NEW PROPERTY button.

4. Property details:

   
   

   Configuration field	Action / Description	Example / Options
   Select Business Entity	Define the scope of the attribute.	Applicable to all or specific legal entities
   Property Name	The user-facing label shown in the UI.	Sales Region
   Property Key Name	The backend system ID (auto-generated but editable before save).	sales_region
   Data Type	The format of the data allowed in the field. See the Reference section for available data types.	Text, Integer, Boolean, etc.
   Default Value	(Optional) The value pre-filled for new records.	N/A or 0
   Mandatory Field	Toggle to require completion before saving.	Yes (Required) / No (Optional)

5. Review and Save: Click ADD.

   ❗️

   Once you click ADD, the Property Key Name and Data Type become permanent. They cannot be changed or deleted later. Ensure the key name is exactly as you want it for your API/integration needs before committing.

3. How-to guides: Advanced management

How to edit an attribute

Attributes can be modified after creation to update UI labels, but structural elements remain locked to prevent breaking integrations:

1. Navigate to Settings: Go to Settings > Custom Attributes.
2. Open the kebab menu (three-dot icon) for the desired attribute and select Edit.

• What you CAN change: Property name, default value, mandatory toggle, and business entity scoping.

  🚧

  For Products, business entity scoping is disabled as products are global in scope.

• What you CANNOT change: Property key name and data type.

How to delete an attribute

🚧

Definitions cannot be deleted. To retire an attribute, we recommend renaming it to [DEPRECATED] Name and disabling the Mandatory toggle.

4. Reference: Technical specifications

Supported data types

API object mapping

Note that the naming convention for the container object varies depending on the object being accessed.

🚧

Note: The Customer object uses custom_data instead of custom_attributes. This is a known inconsistency in the current API and will be aligned in a future release.

API reference

Use these endpoints to manage the definitions of your custom attributes programmatically.

Configuration Metadata