Data Model Fields

Read and manage the custom field definitions (workspace_data_model) for a workspace's clients.

Auth: Bearer token — workspace member (enforced by workspaceGuard). Mutating endpoints (create, update, delete, reorder) additionally require the manage_workspace_settings permission.

Field Types

Type	Description	Example Value
`string`	Text value	`"Gold"`
`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"`

Get Data Model

GET /wallethero-api/workspace/:workspaceId/data-model

Returns all field definitions for the workspace, sorted by sort_order then date_created.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Query Parameters

Parameter	Type	Required	Default	Description
`entity_type`	`string`	No	—	Filter by entity type. Only `client` is supported. When omitted, all fields are returned.

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model?entity_type=client" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "workspace_id": "11111111-1111-1111-1111-111111111111",
    "fields": [
      {
        "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "workspace_id": "11111111-1111-1111-1111-111111111111",
        "field_name": "email",
        "field_label": "Email",
        "field_type": "string",
        "default_value": null,
        "allowed_values": null,
        "is_required": true,
        "is_system": true,
        "sort_order": 0,
        "entity_type": "client",
        "date_created": "2024-01-10T12:00:00Z"
      },
      {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "workspace_id": "11111111-1111-1111-1111-111111111111",
        "field_name": "tier",
        "field_label": "Membership Tier",
        "field_type": "multiselect",
        "default_value": "Bronze",
        "allowed_values": ["Bronze", "Silver", "Gold", "Platinum"],
        "is_required": false,
        "is_system": false,
        "sort_order": 5,
        "entity_type": "client",
        "date_created": "2024-02-01T09:30:00Z"
      }
    ]
  }
}

SDK

typescript

const dataModel = await wh.workspaces.getDataModel(workspaceId);
// dataModel.fields -> WorkspaceDataModelField[]

Create Field

POST /wallethero-api/workspace/:workspaceId/data-model/fields

Creates a new custom field. Created fields are always non-system (is_system: false) and entity_type: "client".

Auth: Bearer token — workspace member with manage_workspace_settings.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Default	Description
`field_name`	`string`	Yes	—	API key. 1–100 chars, must match `^[a-zA-Z_][a-zA-Z0-9_]*$`, must be unique in the workspace, and must not be a reserved name (`first_name`, `last_name`, `email`, `phone`, `birth_date`, `status`, `marketing_consent`).
`field_label`	`string`	Yes	—	Display label (1–255 characters).
`field_type`	`string`	Yes	—	One of `string`, `number`, `multiselect`, `date`, `image`.
`default_value`	`string \| null`	No	`null`	Default value (stored as a string).
`allowed_values`	`array<string> \| null`	No	`null`	Allowed values. Required and non-empty when `field_type` is `multiselect`.
`is_required`	`boolean`	No	`false`	Whether the field is required.
`sort_order`	`number (int)`	No	Auto-assigned (max existing + 1)	Display order (lower = first).
`entity_type`	`string`	No	`"client"`	Entity the field applies to. Only `client` is supported.

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "points",
    "field_label": "Points Balance",
    "field_type": "number",
    "default_value": "0",
    "is_required": true
  }'

Multiselect Field

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "tier",
    "field_label": "Membership Tier",
    "field_type": "multiselect",
    "default_value": "Bronze",
    "allowed_values": ["Bronze", "Silver", "Gold", "Platinum"]
  }'

Response (200)

json

{
  "data": {
    "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "workspace_id": "11111111-1111-1111-1111-111111111111",
    "field_name": "points",
    "field_label": "Points Balance",
    "field_type": "number",
    "default_value": "0",
    "allowed_values": null,
    "is_required": true,
    "is_system": false,
    "sort_order": 6,
    "entity_type": "client",
    "date_created": "2024-06-16T10:00:00Z"
  }
}

SDK

typescript

const field = await wh.workspaces.createDataModelField(workspaceId, {
  field_name: "points",
  field_label: "Points Balance",
  field_type: "number",
  default_value: "0",
  is_required: true,
});

Update Field

PATCH /wallethero-api/workspace/:workspaceId/data-model/fields/:fieldId

Updates an existing field. All body fields are optional (a partial of the create body). For system fields, field_name and field_type cannot be changed; attempting to change them returns an error.

Auth: Bearer token — workspace member with manage_workspace_settings.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`fieldId`	`string (UUID)`	Field identifier

Request Body

All fields are optional; only provided fields are updated. Same constraints as Create Field.

Field	Type	Description
`field_name`	`string`	New API key. Must be unique and not reserved. Cannot change for system fields.
`field_label`	`string`	Display label (1–255 characters).
`field_type`	`string`	One of `string`, `number`, `multiselect`, `date`, `image`. Cannot change for system fields.
`default_value`	`string \| null`	Default value.
`allowed_values`	`array<string> \| null`	Allowed values. Must be non-empty if the resulting `field_type` is `multiselect`.
`is_required`	`boolean`	Whether the field is required.
`sort_order`	`number (int)`	Display order.
`entity_type`	`string`	Only `client` is supported.

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/fields/FIELD_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_label": "Loyalty Points",
    "default_value": "100"
  }'

Response (200)

json

{
  "data": {
    "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "workspace_id": "11111111-1111-1111-1111-111111111111",
    "field_name": "points",
    "field_label": "Loyalty Points",
    "field_type": "number",
    "default_value": "100",
    "allowed_values": null,
    "is_required": true,
    "is_system": false,
    "sort_order": 6,
    "entity_type": "client"
  }
}

SDK

typescript

const field = await wh.workspaces.updateDataModelField(workspaceId, fieldId, {
  field_label: "Loyalty Points",
  default_value: "100",
});

Delete Field

DELETE /wallethero-api/workspace/:workspaceId/data-model/fields/:fieldId

Deletes a custom field. System fields cannot be deleted and return an error.

Auth: Bearer token — workspace member with manage_workspace_settings.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`fieldId`	`string (UUID)`	Field identifier

WARNING

Deleting a field removes the definition only. Values already stored on clients are not removed; they simply stop being validated.

Example Request

bash

curl -X DELETE "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/fields/FIELD_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{ "success": true, "message": "Field deleted" }

SDK

typescript

await wh.workspaces.deleteDataModelField(workspaceId, fieldId);

Reorder Fields

POST /wallethero-api/workspace/:workspaceId/data-model/reorder

Sets the sort_order of fields to match the order of the provided field_ids array (index 0 first). All IDs must belong to the workspace.

Auth: Bearer token — workspace member with manage_workspace_settings.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Description
`field_ids`	`array<string (UUID)>`	Yes	Field identifiers in the desired display order.

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_ids": [
      "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "cccccccc-cccc-cccc-cccc-cccccccccccc"
    ]
  }'

Response (200)

json

{ "success": true, "message": "Fields reordered" }

SDK

typescript

await wh.workspaces.reorderDataModelFields(workspaceId, [
  "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "cccccccc-cccc-cccc-cccc-cccccccccccc",
]);

Get Default Values

GET /wallethero-api/workspace/:workspaceId/data-model/defaults

Returns a map of field_name → default_value for every non-system field that has a default_value set. System fields and fields without a default are omitted.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/data-model/defaults" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "points": "0",
    "tier": "Bronze"
  }
}

TIP

Default values are stored and returned as strings (the raw default_value of each field).

SDK

typescript

const defaults = await wh.workspaces.getDataModelDefaults(workspaceId);
// { points: "0", tier: "Bronze" }

Data Model Fields ​

Field Types ​

Get Data Model ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Create Field ​

Path Parameters ​

Request Body ​

Example Request ​

Multiselect Field ​

Response (200) ​

SDK ​

Update Field ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete Field ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Reorder Fields ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Get Default Values ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Data Model Fields

Field Types

Get Data Model

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Create Field

Path Parameters

Request Body

Example Request

Multiselect Field

Response (200)

SDK

Update Field

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete Field

Path Parameters

Example Request

Response (200)

SDK

Reorder Fields

Path Parameters

Request Body

Example Request

Response (200)

SDK

Get Default Values

Path Parameters

Example Request

Response (200)

SDK