Custom Fields

The Custom Fields API allows you to define and manage custom data fields for your loyalty program.

Endpoints

List Custom Fields

Get all custom field definitions for your organization.

Endpoint: GET /custom-fields

Query Parameters:

Parameter	Type	Required	Description
type	string	No	Filter by field type
status	string	No	Filter by status (active, deleted)

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "customFields": [
      {
        "fieldId": "field_38de5a92-fa93-47ac-a33c-84ee4fd85b97",
        "orgId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Favorite Team",
        "key": "favorite_team",
        "type": "select",
        "description": "User's favorite team",
        "required": true,
        "options": ["Lakers", "Warriors", "Celtics", "Heat"],
        "validation": null,
        "defaultValue": null,
        "status": "active",
        "metadata": {},
        "createdAt": "2025-10-05T17:41:55.745Z",
        "updatedAt": "2025-10-05T17:41:55.745Z",
        "createdBy": "Admin"
      }
    ],
    "count": 1
  }
}

Create Custom Field

Define a new custom field.

Endpoint: POST /custom-fields

Request Body:

Field	Type	Required	Description
name	string	Yes	Display name for the field
key	string	Yes	Unique key (alphanumeric with underscores)
type	string	Yes	Field type: string, number, boolean, date, select, multi-select
description	string	No	Field description
required	boolean	No	Whether the field is required (default: false)
options	array	Conditional	Required for select and multi-select types
validation	object	No	Validation rules
defaultValue	any	No	Default value for the field
status	string	No	Field status (default: active)
metadata	object	No	Additional metadata

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Favorite Team",
    "key": "favorite_team",
    "type": "select",
    "description": "User favorite sports team",
    "required": true,
    "options": ["Lakers", "Warriors", "Celtics", "Heat"]
  }'

Example Response:

{
  "success": true,
  "data": {
    "fieldId": "field_38de5a92-fa93-47ac-a33c-84ee4fd85b97",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Favorite Team",
    "key": "favorite_team",
    "type": "select",
    "description": "User favorite sports team",
    "required": true,
    "options": ["Lakers", "Warriors", "Celtics", "Heat"],
    "validation": null,
    "defaultValue": null,
    "status": "active",
    "metadata": {},
    "createdAt": "2025-10-05T17:41:55.745Z",
    "updatedAt": "2025-10-05T17:41:55.745Z",
    "createdBy": "Admin"
  }
}

Get Custom Field

Retrieve a specific custom field by ID.

Endpoint: GET /custom-fields/{fieldId}

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/custom-fields/field_38de5a92-fa93-47ac-a33c-84ee4fd85b97" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "fieldId": "field_38de5a92-fa93-47ac-a33c-84ee4fd85b97",
    "name": "Favorite Team",
    "key": "favorite_team",
    "type": "select",
    "options": ["Lakers", "Warriors", "Celtics", "Heat"],
    "status": "active"
  }
}

Update Custom Field

Update an existing custom field.

Endpoint: PUT /custom-fields/{fieldId}

Request Body: Same fields as Create, all optional

Example Request:

curl -X PUT "https://api.monterosa.cloud/loyalty/v1/custom-fields/field_38de5a92-fa93-47ac-a33c-84ee4fd85b97" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "options": ["Lakers", "Warriors", "Celtics", "Heat", "Bulls"]
  }'

Example Response:

{
  "success": true,
  "data": {
    "fieldId": "field_38de5a92-fa93-47ac-a33c-84ee4fd85b97",
    "name": "Favorite Team",
    "options": ["Lakers", "Warriors", "Celtics", "Heat", "Bulls"],
    "updatedAt": "2025-10-05T18:00:00.000Z",
    "updatedBy": "Admin"
  }
}

Delete Custom Field

Soft delete a custom field. The field is marked as deleted but not removed from the database.

Endpoint: DELETE /custom-fields/{fieldId}

Example Request:

curl -X DELETE "https://api.monterosa.cloud/loyalty/v1/custom-fields/field_38de5a92-fa93-47ac-a33c-84ee4fd85b97" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "message": "Custom field deleted successfully"
  }
}

Field Types

string

Text values of any length.

number

Numeric values (integers or decimals).

boolean

True/false values.

date

ISO 8601 formatted date strings.

select

Single selection from predefined options. Requires options array.

multi-select

Multiple selections from predefined options. Requires options array.

Validation Rules

Custom validation rules can be defined in the validation object:

{
  "validation": {
    "min": 0,
    "max": 100,
    "pattern": "^[A-Z]{2}$",
    "minLength": 2,
    "maxLength": 50
  }
}

Error Responses

400 Bad Request:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "details": {
      "errors": [
        "key is required and must be alphanumeric with underscores only",
        "options array is required for select and multi-select types"
      ]
    }
  }
}

404 Not Found:

{
  "success": false,
  "error": {
    "message": "Custom field not found"
  }
}

Best Practices

1. Key Naming: Use lowercase with underscores (e.g., favorite_team, birth_date)

2. Required Fields: Carefully consider which fields to mark as required

3. Validation: Define validation rules to ensure data quality

4. Soft Deletes: Deleted fields are preserved for data integrity

5. Options: Keep select option lists manageable (< 50 options)