User Schema

The User Schema API provides schema discovery for user properties, enabling dynamic segment building and user targeting in your loyalty campaigns.

Overview

The User Schema endpoint returns a comprehensive schema of all available user properties for your organization, combining:

1. Standard Properties - 23 built-in properties available to all organizations

2. Custom Fields - Organisation-specific fields defined via the Custom Fields API

3. Integration Properties - Data from connected systems (CRM, CDP, etc.)

This enables:

• Dynamic segment builder UIs

• API-driven segmentation

• Self-documenting user properties

• Type-safe filtering and targeting

Endpoints

Get User Schema

Retrieve all available user properties for segmentation and filtering.

Endpoint: GET /users/schema

Query Parameters:

Parameter	Type	Required	Description
includeInactive	boolean	No	Include inactive custom fields (default: false)

Example Request:

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

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "properties": [
      {
        "key": "userId",
        "name": "User ID",
        "type": "string",
        "category": "identity",
        "description": "Unique user identifier",
        "operators": ["equals", "notEquals", "in", "notIn"],
        "example": "user123"
      },
      {
        "key": "tier",
        "name": "User Tier",
        "type": "string",
        "category": "loyalty",
        "description": "Current loyalty tier",
        "operators": ["equals", "notEquals", "in", "notIn"],
        "options": ["bronze", "silver", "gold", "platinum", "diamond"],
        "example": "gold"
      },
      {
        "key": "points",
        "name": "Points Balance",
        "type": "number",
        "category": "loyalty",
        "description": "Current points balance",
        "operators": ["equals", "notEquals", "greaterThan", "lessThan", "between"],
        "example": 1500
      },
      {
        "key": "custom.favorite_team",
        "name": "Favorite Team",
        "type": "select",
        "category": "custom",
        "description": "User's favorite team",
        "operators": ["equals", "notEquals", "in", "notIn"],
        "options": ["Lakers", "Warriors", "Celtics", "Heat"],
        "source": "custom_field",
        "fieldId": "field_38de5a92-fa93-47ac-a33c-84ee4fd85b97"
      }
    ],
    "operators": {
      "equals": {
        "types": ["string", "number", "date"],
        "description": "Exactly equals"
      },
      "greaterThan": {
        "types": ["number", "date"],
        "description": "Greater than"
      },
      "contains": {
        "types": ["string", "array"],
        "description": "Contains substring or item"
      }
    },
    "categories": [
      {
        "key": "identity",
        "name": "Identity",
        "description": "Basic user identification"
      },
      {
        "key": "loyalty",
        "name": "Loyalty",
        "description": "Points, tiers, and rewards"
      },
      {
        "key": "custom",
        "name": "Custom Fields",
        "description": "Organisation-defined fields"
      }
    ],
    "sources": {
      "standard": 23,
      "customFields": 1,
      "integrations": 0
    },
    "examples": [
      {
        "name": "VIP Users",
        "description": "Users with gold tier or higher and 5000+ lifetime points",
        "criteria": [
          {
            "field": "tier",
            "operator": "in",
            "value": ["gold", "platinum", "diamond"]
          },
          {
            "field": "lifetimePoints",
            "operator": "greaterThan",
            "value": 5000
          }
        ]
      }
    ]
  }
}

Property Types

Standard Properties (23 built-in)

Identity

• userId - Unique user identifier

• email - User email address

• createdAt - Registration date

• lastActiveAt - Last activity timestamp

Loyalty

• tier - Current loyalty tier (bronze, silver, gold, platinum, diamond)

• points - Current points balance

• lifetimePoints - Total points earned all-time

• xp - Experience points

• level - User level based on XP

• coins - Coins balance

Achievements

• badges - Array of earned badge IDs

• badgeCount - Total badges earned

Engagement

• streak - Current consecutive days active

• longestStreak - Longest streak achieved

• transactionCount - Total transactions

Location

• country - ISO 3166-1 alpha-2 country code

• city - User city

• timezone - User timezone

Preferences

• language - ISO 639-1 language code

Social

• referralCount - Number of users referred

• referredBy - User ID of referrer

Metadata

• segments - Array of segment IDs

• tags - Custom tags array

Custom Field Properties

Properties defined via the Custom Fields API are automatically included with:

• Namespace: Prefixed with custom. (e.g., custom.favorite_team)

• Type Mapping: Field types map to appropriate operators

• Options: Select and multi-select fields include available options

• Source Tracking: Includes fieldId for reference

Integration Properties (Future)

Properties from connected systems:

• Salesforce: integration.salesforce.account_type

• HubSpot: integration.hubspot.lifecycle_stage

• Segment: integration.segment.computed_traits

Operators

Each property type supports specific operators:

String Operators

• equals - Exact match

• notEquals - Not equal

• contains - Contains substring

• notContains - Does not contain

• startsWith - Starts with

• endsWith - Ends with

• in - One of (list)

• notIn - Not one of (list)

Number Operators

• equals - Exact match

• notEquals - Not equal

• greaterThan - Greater than

• lessThan - Less than

• between - Between two values

Date Operators

• equals - Exact date match

• before - Before date

• after - After date

• between - Between two dates

Array Operators

• contains - Contains item

• notContains - Does not contain

• containsAll - Contains all items

• containsAny - Contains any item

Existence Operators

• exists - Field has a value

• notExists - Field is null/undefined

Categories

Properties are organized into logical categories:

Category	Description	Example Properties
identity	Basic user identification	userId, email, createdAt
loyalty	Points, tiers, and rewards	tier, points, lifetimePoints
achievements	Badges and accomplishments	badges, badgeCount
engagement	Activity and participation	streak, transactionCount
segmentation	Segment membership	segments
location	Geographic information	country, city, timezone
preferences	User preferences	language
social	Referrals and connections	referralCount, referredBy
metadata	Custom tags and data	tags
custom	Organisation-defined fields	custom.*
integration	Connected system data	integration.*

Use Cases

Dynamic Segment Builder UI

Build a segment builder that adapts to your organization's schema:

// Fetch schema
const response = await fetch('/v1/users/schema', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Monterosa-Org-ID': 'YOUR_ORG_ID'
  }
});

const { properties, categories } = await response.json().data;

// Group properties by category for UI
const propertiesByCategory = categories.map(cat => ({
  ...cat,
  properties: properties.filter(p => p.category === cat.key)
}));

// Render dropdown
properties.forEach(prop => {
  console.log(`${prop.name}: ${prop.operators.join(', ')}`);
});

Campaign Targeting

Use schema to validate targeting criteria:

// Get available properties
const schema = await getSchema();

// Create campaign with validated criteria
await createCampaign({
  name: "VIP Rewards",
  segmentCriteria: [
    { field: "tier", operator: "in", value: ["platinum", "diamond"] },
    { field: "custom.favorite_team", operator: "equals", value: "Lakers" }
  ]
});

API-Driven Segmentation

Discover and use properties programmatically:

const { properties } = await getSchema();

// Find all loyalty properties
const loyaltyProps = properties.filter(p => p.category === 'loyalty');

// Find properties with numeric operators
const numericProps = properties.filter(p =>
  p.operators.includes('greaterThan')
);

// Create dynamic segments
const highValueUsers = {
  criteria: [
    { field: 'lifetimePoints', operator: 'greaterThan', value: 10000 }
  ]
};

Type-Safe Filtering

Use operator information to build type-safe filters:

const property = properties.find(p => p.key === 'points');

// Check if operator is supported
if (property.operators.includes('between')) {
  // Safe to use between operator
  const criteria = {
    field: 'points',
    operator: 'between',
    value: [1000, 5000]
  };
}

Integration with Custom Fields

Custom fields defined via the Custom Fields API are automatically included in the schema:

Step 1: Create Custom Field

curl -X POST "https://api.monterosa.cloud/loyalty/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -d '{
    "name": "Favorite Team",
    "key": "favorite_team",
    "type": "select",
    "options": ["Lakers", "Warriors", "Celtics"]
  }'

Step 2: Retrieve Schema

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

Result:

{
  "properties": [
    {
      "key": "custom.favorite_team",
      "name": "Favorite Team",
      "type": "select",
      "category": "custom",
      "operators": ["equals", "notEquals", "in", "notIn"],
      "options": ["Lakers", "Warriors", "Celtics"],
      "source": "custom_field"
    }
  ]
}

Schema Evolution

The schema adapts to your organization:

1. Add Custom Field → Automatically appears in schema

2. Update Field Options → Options refresh in schema

3. Delete Custom Field → Removed from schema (unless includeInactive=true)

4. Connect Integration → Integration properties added automatically

Best Practices

1. Cache Schema: Cache the schema response for 5-10 minutes to reduce API calls

2. Category Organisation: Group properties by category in your UI for better UX

3. Operator Validation: Check operators array before allowing filter operations

4. Custom Field Namespace: Always prefix custom fields with custom. in criteria

5. Type Safety: Use type field to render appropriate input controls (text, number, select)

6. Example Usage: Reference the examples array for common segment patterns

7. Source Tracking: Use source field to distinguish between standard, custom, and integration properties

Error Responses

401 Unauthorized:

{
  "success": false,
  "error": {
    "message": "Invalid token"
  }
}

500 Internal Server Error:

{
  "success": false,
  "error": {
    "message": "Failed to get user schema"
  }
}

Schema Response Example

Full example showing all three property sources:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "properties": [
      // Standard property
      {
        "key": "tier",
        "name": "User Tier",
        "type": "string",
        "category": "loyalty",
        "operators": ["equals", "notEquals", "in", "notIn"],
        "options": ["bronze", "silver", "gold", "platinum", "diamond"]
      },
      // Custom field
      {
        "key": "custom.favorite_team",
        "name": "Favorite Team",
        "type": "select",
        "category": "custom",
        "source": "custom_field",
        "fieldId": "field_abc123",
        "operators": ["equals", "notEquals", "in", "notIn"],
        "options": ["Lakers", "Warriors"]
      },
      // Integration property (future)
      {
        "key": "integration.salesforce.account_type",
        "name": "Account Type",
        "type": "string",
        "category": "integration",
        "source": "salesforce",
        "operators": ["equals", "notEquals", "in", "notIn"]
      }
    ],
    "categories": [...],
    "operators": {...},
    "sources": {
      "standard": 23,
      "customFields": 1,
      "integrations": 1
    }
  }
}