Data Model

The data model defines the custom fields that live on a workspace's clients. Each workspace has a set of workspace_data_model field definitions that drive validation, default values, and consistent field metadata across the API and UI.

All data-model endpoints are workspace-scoped: the caller must be a member of the workspace (enforced by the workspaceGuard middleware). Mutating endpoints (create, update, delete, reorder) additionally require the manage_workspace_settings permission, enforced inside the service.

Base URL: https://api.wallethero.app

Sub-pages

• Fields — read the data model, create/update/delete fields, reorder fields, and fetch default values.
• Validation — validate a set of custom field values against the data model.

Endpoints

Method	Endpoint	Page
GET	/wallethero-api/workspace/:workspaceId/data-model	Fields
POST	/wallethero-api/workspace/:workspaceId/data-model/fields	Fields
PATCH	/wallethero-api/workspace/:workspaceId/data-model/fields/:fieldId	Fields
DELETE	/wallethero-api/workspace/:workspaceId/data-model/fields/:fieldId	Fields
POST	/wallethero-api/workspace/:workspaceId/data-model/reorder	Fields
GET	/wallethero-api/workspace/:workspaceId/data-model/defaults	Fields
POST	/wallethero-api/workspace/:workspaceId/data-model/validate	Validation

Field Types

Type	Description	Example Value
string	Text value	"Gold", "Downtown Store"
number	Numeric value	1500, 99.99
multiselect	Value constrained to a fixed list of allowed_values	"sports"
date	Date string in YYYY-MM-DD format	"2024-01-15"
image	A Directus file UUID or an http(s):// URL	"https://cdn.example.com/logo.png"

TIP

multiselect fields require a non-empty allowed_values list. A submitted value is validated as a single scalar that must be one of the allowed_values.

Field Structure

The WorkspaceDataModelField shape returned by the API:

interface WorkspaceDataModelField {
  id: string;                  // UUID
  workspace_id: string;        // UUID
  field_name: string;          // API key, e.g. "points"
  field_label: string;         // Display label, e.g. "Points Balance"
  field_type: "string" | "number" | "multiselect" | "date" | "image";
  default_value?: string | null;   // Default value (stored as string)
  allowed_values?: string[] | null; // Allowed values (required for multiselect)
  is_required: boolean;        // Whether the field is required
  is_system: boolean;          // System-managed field (cannot be deleted)
  sort_order: number;          // Display order (lower = first)
  entity_type: "client";       // Entity the field applies to
  date_created?: string;       // ISO 8601 timestamp
  user_created?: string;
  date_updated?: string;
  user_updated?: string;
}

System Fields

Every workspace is seeded with a set of system fields (is_system: true) for clients:

field_name	field_label	field_type	Required
email	Email	string	Yes
first_name	First Name	string	No
last_name	Last Name	string	No
phone	Phone	string	No
birth_date	Birth Date	date	No

System fields cannot be deleted, and their field_name and field_type cannot be changed. Other attributes (e.g. field_label, is_required, sort_order) may be updated.

Reserved Field Names

Custom field_name values cannot collide with the built-in client scalar columns. The following names are reserved and rejected when creating or renaming a field:

first_name, last_name, email, phone, birth_date, status, marketing_consent

A field_name must also match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ (start with a letter or underscore; alphanumerics and underscores only) and be unique within the workspace.

SDK

Data-model methods live on wh.workspaces:

import { WalletHero } from "@wallethero/sdk";

const wh = new WalletHero({ apiToken: "YOUR_TOKEN" });

const dataModel = await wh.workspaces.getDataModel(workspaceId);