User Profiles

The User Profiles API allows you to manage user profile schemas and user data. This includes CRUD operations on user profiles, schema management with versioning, GDPR compliance features (data export and consent tracking), and user operations like enrollment and check-in.

Overview

Key Features:

Dynamic profile schema management with versioning
User CRUD operations (Create, Read, Update, Delete)
GDPR compliance (data export, consent tracking)
User enrollment and check-in
Custom fields support
Schema history tracking

Profile Schema Management

Get Profile Schema

Retrieve the active profile schema or a specific version.

GET /v1/profiles/schema

Query Parameters:

Parameter

Type

Required

Description

version

string

Specific schema version (e.g., v1.0.0). If not provided, returns active schema

Example Request (Active Schema):

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

Example Request (Specific Version):

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

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v1.2.0",
    "isActive": true,
    "schema": {
      "fields": [
        {
          "name": "email",
          "type": "string",
          "required": true,
          "unique": true
        },
        {
          "name": "firstName",
          "type": "string",
          "required": false
        },
        {
          "name": "lastName",
          "type": "string",
          "required": false
        },
        {
          "name": "dateOfBirth",
          "type": "date",
          "required": false
        },
        {
          "name": "tier",
          "type": "string",
          "enum": ["bronze", "silver", "gold", "platinum"],
          "default": "bronze"
        },
        {
          "name": "points",
          "type": "number",
          "default": 0
        },
        {
          "name": "customFields",
          "type": "object",
          "required": false
        }
      ]
    },
    "createdAt": "2025-10-01T10:00:00.000Z",
    "createdBy": "[email protected]"
  }
}

Update Profile Schema

Create a new schema version. Schema updates are versioned to maintain data integrity.

PUT /v1/profiles/schema

Request Body:

Field

Type

Required

Description

version

string

Yes

New version identifier (e.g., v1.3.0)

schema

object

Yes

Schema definition with fields array

setActive

boolean

Set as active schema (default: true)

Example Request:

curl -X PUT "https://api.monterosa.cloud/loyalty/v1/profiles/schema" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1.3.0",
    "setActive": true,
    "schema": {
      "fields": [
        {
          "name": "email",
          "type": "string",
          "required": true,
          "unique": true,
          "validation": {
            "regex": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
          }
        },
        {
          "name": "phoneNumber",
          "type": "string",
          "required": false
        },
        {
          "name": "tier",
          "type": "string",
          "enum": ["bronze", "silver", "gold", "platinum"],
          "default": "bronze"
        },
        {
          "name": "points",
          "type": "number",
          "default": 0
        },
        {
          "name": "preferences",
          "type": "object",
          "properties": {
            "newsletter": { "type": "boolean", "default": true },
            "smsNotifications": { "type": "boolean", "default": false }
          }
        }
      ]
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "v1.3.0",
    "isActive": true,
    "schema": {
      "fields": [...]
    },
    "createdAt": "2025-10-11T10:00:00.000Z",
    "createdBy": "[email protected]"
  }
}

Get Schema History

Retrieve all schema versions for your organization.

GET /v1/profiles/schema/history

Query Parameters:

Parameter

Type

Required

Description

limit

number

Number of versions to return (default: 50)

cursor

string

Pagination cursor

Example Request:

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

Example Response:

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "v1.3.0",
        "isActive": true,
        "createdAt": "2025-10-11T10:00:00.000Z",
        "createdBy": "[email protected]"
      },
      {
        "version": "v1.2.0",
        "isActive": false,
        "createdAt": "2025-10-01T10:00:00.000Z",
        "createdBy": "[email protected]"
      },
      {
        "version": "v1.0.0",
        "isActive": false,
        "createdAt": "2025-09-01T10:00:00.000Z",
        "createdBy": "system"
      }
    ],
    "count": 3,
    "cursor": null
  }
}

User Profile Operations

Get User Profile

Retrieve a specific user's profile data.

GET /v1/profiles/users/{userId}

Path Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

Example Request:

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

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user_123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "tier": "gold",
    "points": 5000,
    "xp": 1200,
    "coins": 500,
    "badges": ["badge_first_login", "badge_quiz_master"],
    "customFields": {
      "favoriteTeam": "Team A",
      "newsletter": true,
      "birthYear": 1990
    },
    "status": "active",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-10-11T14:30:00.000Z"
  }
}

Update User Profile

Update a user's profile data.

PUT /v1/profiles/users/{userId}

Path Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

Request Body: Any profile fields to update

Example Request:

curl -X PUT "https://api.monterosa.cloud/loyalty/v1/profiles/users/user_123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "customFields": {
      "favoriteTeam": "Team B",
      "newsletter": true
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user_123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith",
    "tier": "gold",
    "points": 5000,
    "customFields": {
      "favoriteTeam": "Team B",
      "newsletter": true
    },
    "updatedAt": "2025-10-11T15:00:00.000Z"
  }
}

Delete User Profile

Soft-delete a user profile (GDPR compliance).

DELETE /v1/profiles/users/{userId}

Path Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

Query Parameters:

Parameter

Type

Required

Description

hard

boolean

Permanently delete (default: false for soft delete)

Example Request (Soft Delete):

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

Example Response:

{
  "success": true,
  "data": {
    "message": "User profile deleted successfully",
    "userId": "user_123",
    "deletedAt": "2025-10-11T15:30:00.000Z"
  }
}

Export User Data

Generate a complete data export for a user (GDPR Article 15 - Right to Access).

POST /v1/profiles/users/{userId}/export

Path Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

Request Body:

Field

Type

Required

Description

format

string

Export format: json, csv (default: json)

includeTransactions

boolean

Include transaction history (default: true)

includeActivity

boolean

Include activity logs (default: true)

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/profiles/users/user_123/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "includeTransactions": true,
    "includeActivity": true
  }'

Example Response:

{
  "success": true,
  "data": {
    "exportId": "export_abc123",
    "userId": "user_123",
    "status": "completed",
    "downloadUrl": "https://s3.amazonaws.com/exports/user_123_export.json",
    "expiresAt": "2025-10-12T15:30:00.000Z",
    "createdAt": "2025-10-11T15:30:00.000Z"
  }
}

Export Data Structure:

{
  "userId": "user_123",
  "profile": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "tier": "gold",
    "points": 5000
  },
  "transactions": [
    {
      "transactionId": "txn_xyz789",
      "type": "points",
      "amount": 100,
      "reason": "Video watched",
      "createdAt": "2025-10-05T10:00:00.000Z"
    }
  ],
  "activity": [
    {
      "activityId": "act_def456",
      "type": "campaign_completed",
      "timestamp": "2025-10-05T10:00:00.000Z"
    }
  ],
  "consent": [
    {
      "type": "newsletter",
      "granted": true,
      "timestamp": "2025-01-15T10:00:00.000Z"
    }
  ],
  "exportedAt": "2025-10-11T15:30:00.000Z"
}

Record user consent for data processing (GDPR Article 6 - Lawful Basis).

POST /v1/profiles/users/{userId}/consent

Path Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

Request Body:

Field

Type

Required

Description

consentType

string

Yes

Type of consent: marketing, newsletter, analytics, data_processing

granted

boolean

Yes

Whether consent is granted or revoked

metadata

object

Additional context (e.g., IP address, user agent)

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/profiles/users/user_123/consent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "consentType": "newsletter",
    "granted": true,
    "metadata": {
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0",
      "source": "preferences_page"
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "userId": "user_123",
    "consentType": "newsletter",
    "granted": true,
    "recordedAt": "2025-10-11T16:00:00.000Z",
    "metadata": {
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0",
      "source": "preferences_page"
    }
  }
}

User Operations

User Enrollment

Enroll a new user in the loyalty program.

POST /v1/users/enroll

Request Body:

Field

Type

Required

Description

userId

string

Yes

Unique user identifier

string

User email address

metadata

object

Additional enrollment data

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/users/enroll" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_456",
    "email": "[email protected]",
    "metadata": {
      "source": "mobile_app",
      "referralCode": "FRIEND123"
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "userId": "user_456",
    "email": "[email protected]",
    "tier": "bronze",
    "points": 0,
    "xp": 0,
    "coins": 0,
    "enrolledAt": "2025-10-11T16:30:00.000Z",
    "status": "active"
  }
}

User Check-in

Record a user check-in (daily login, venue check-in, etc.).

POST /v1/users/checkin

Request Body:

Field

Type

Required

Description

userId

string

Yes

User ID

type

string

Check-in type: daily, venue, event (default: daily)

metadata

object

Additional check-in data

Example Request:

curl -X POST "https://api.monterosa.cloud/loyalty/v1/users/checkin" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "type": "daily",
    "metadata": {
      "location": "mobile_app",
      "platform": "iOS"
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "userId": "user_123",
    "checkinId": "checkin_abc123",
    "type": "daily",
    "timestamp": "2025-10-11T17:00:00.000Z",
    "streak": {
      "current": 7,
      "longest": 15
    },
    "rewards": [
      {
        "type": "points",
        "amount": 10,
        "reason": "Daily check-in"
      }
    ]
  }
}

Get User Schema

Retrieve the profile schema for user-facing applications.

GET /v1/users/schema

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": {
    "version": "v1.2.0",
    "schema": {
      "fields": [
        {
          "name": "email",
          "type": "string",
          "required": true,
          "label": "Email Address"
        },
        {
          "name": "firstName",
          "type": "string",
          "required": false,
          "label": "First Name"
        },
        {
          "name": "tier",
          "type": "string",
          "enum": ["bronze", "silver", "gold", "platinum"],
          "readonly": true
        }
      ]
    }
  }
}

Get User Challenges

Retrieve active challenges for a user.

GET /v1/users/challenges

Query Parameters:

Parameter

Type

Required

Description

userId

string

Yes

User ID

status

string

Filter by status: active, completed, expired

Example Request:

curl -X GET "https://api.monterosa.cloud/loyalty/v1/users/challenges?userId=user_123&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Monterosa-Org-ID: YOUR_ORG_UUID"

Example Response:

{
  "success": true,
  "data": {
    "challenges": [
      {
        "campaignId": "camp_welcome_challenge",
        "name": "Welcome Challenge",
        "type": "Challenge",
        "progress": {
          "completedSteps": 2,
          "totalSteps": 5,
          "completionPercentage": 40.0
        },
        "expiresAt": "2025-10-18T10:00:00.000Z",
        "status": "active"
      }
    ],
    "count": 1
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "message": "userId is required"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "message": "User profile not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "message": "User with this email already exists"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "message": "Failed to update user profile"
  }
}

Best Practices

Schema Versioning: Always version schemas when making changes
GDPR Compliance: Use export and consent endpoints for GDPR requirements
Soft Deletes: Use soft delete (default) unless hard delete is required
Custom Fields: Use custom fields for organization-specific data
Consent Tracking: Record all consent changes with metadata
Data Minimization: Only collect necessary user data

Audience API - User-facing profile operations
Transactions API - Track user point/coin transactions
Campaigns API - User challenge and campaign progress

Support

For questions about the User Profiles API:

Documentation: https://products.monterosa.co/mic/reference
Support: [email protected]

Last updated 26 days ago

Overview

Profile Schema Management

Get Profile Schema

Update Profile Schema

Get Schema History

User Profile Operations

Get User Profile

Update User Profile

Delete User Profile

GDPR Features

Export User Data

Record User Consent

User Operations

User Enrollment

User Check-in

Get User Schema

Get User Challenges

Error Responses

400 Bad Request

404 Not Found

409 Conflict

500 Internal Server Error

Best Practices

Related APIs

Support