Onboarding Analytics Admin
Base URL: https://api.fursahub.com/api/v1
Short Description: Admin endpoints for analyzing user demographics and onboarding data. Provides summary statistics, detailed breakdowns by preference page, and user segmentation capabilities. Data collected here powers recommendations and business insights.
Hints:
- All endpoints require ADMIN or SUPER_ADMIN role
- Demographics data comes from user responses to onboarding preference pages
- Use these endpoints for admin dashboards, reports, and recommendation engine input
- Internal service methods available for social media and recommendation features
Analytics Data Flow
┌─────────────────────────────────────────────────────────────────────────┐
│ ANALYTICS DATA FLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ DATA COLLECTION (During Onboarding): │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ User completes preference pages: │ │
│ │ • "interests" → ["jobs", "funding", "events"] │ │
│ │ • "goals" → ["find_job", "start_business"] │ │
│ │ • "experience" → ["student", "0-2_years"] │ │
│ │ │ │
│ │ Stored in: user_onboarding_response table │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ DATA ANALYSIS (Admin Dashboard): │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ GET /onboarding/analytics/summary │ │
│ │ • Total users, completion rates │ │
│ │ • Breakdown by status, auth provider, language, theme │ │
│ │ │ │
│ │ GET /onboarding/analytics/demographics │ │
│ │ • Per-page option counts and percentages │ │
│ │ • "60% of users interested in jobs" │ │
│ │ • "45% want to start a business" │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ DATA USAGE (Internal Systems): │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Recommendation Engine: │ │
│ │ • getUserSelections(userId, "interests") │ │
│ │ • getUsersWithSimilarPreferences(userId) │ │
│ │ • Show relevant opportunities based on user interests │ │
│ │ │ │
│ │ Content Personalization: │ │
│ │ • User interested in "funding" → Show grants first │ │
│ │ • User goal is "learn_skills" → Prioritize courses │ │
│ │ │ │
│ │ User Segmentation: │ │
│ │ • getUsersBySelection("goals", "start_business") │ │
│ │ • Target campaigns to specific user groups │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Endpoints
1. Get Summary Statistics
Purpose: Get high-level onboarding statistics for admin dashboard.
Endpoint: GET {base_url}/onboarding/analytics/summary
Access Level: 🔒 Protected (Admin Only)
Authentication: Bearer Token (ROLE_ADMIN or ROLE_SUPER_ADMIN)
Request Headers:
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer {accessToken} |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Summary retrieved",
"action_time": "2025-01-05T14:00:00",
"data": {
"totalUsers": 5000,
"completedOnboarding": 4200,
"completionRate": 84.0,
"totalPagesConfigured": 3,
"byStatus": {
"COMPLETED": 4200,
"PENDING_PHONE_VERIFICATION": 300,
"PENDING_PREFERENCES": 350,
"PENDING_PROFILE_COMPLETION": 100,
"PENDING_EMAIL_VERIFICATION": 50
},
"byAuthProvider": {
"GOOGLE": 3500,
"APPLE": 800,
"EMAIL": 700
},
"byLanguage": {
"en": 2000,
"sw": 2500,
"fr": 400,
"zh": 100
},
"byTheme": {
"SYSTEM": 3000,
"DARK": 1200,
"LIGHT": 800
}
}
}
Success Response Fields:
| Field | Description |
|---|---|
| totalUsers | Total registered users |
| completedOnboarding | Users who finished all onboarding steps |
| completionRate | Percentage of users who completed onboarding |
| totalPagesConfigured | Number of active preference pages |
| byStatus | User count per onboarding status |
| byAuthProvider | User count per authentication method |
| byLanguage | User count per language preference |
| byTheme | User count per theme preference |
2. Get Demographics
Purpose: Get detailed breakdown of user responses per preference page.
Endpoint: GET {base_url}/onboarding/analytics/demographics
Access Level: 🔒 Protected (Admin Only)
Authentication: Bearer Token
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Demographics retrieved",
"action_time": "2025-01-05T14:05:00",
"data": {
"totalUsersAnalyzed": 4200,
"generatedAt": "2025-01-05T14:05:00",
"pages": [
{
"pageId": "550e8400-e29b-41d4-a716-446655440001",
"categoryKey": "interests",
"title": "Your Interests",
"pageOrder": 1,
"totalResponses": 4200,
"skippedCount": 0,
"responseRate": 100.0,
"options": [
{ "key": "jobs", "label": "Jobs", "count": 2520, "percentage": 60.0 },
{ "key": "funding", "label": "Funding", "count": 1890, "percentage": 45.0 },
{ "key": "events", "label": "Events", "count": 1260, "percentage": 30.0 },
{ "key": "skills", "label": "Skills Training", "count": 1680, "percentage": 40.0 },
{ "key": "networking", "label": "Networking", "count": 840, "percentage": 20.0 }
]
},
{
"pageId": "550e8400-e29b-41d4-a716-446655440002",
"categoryKey": "goals",
"title": "Your Goals",
"pageOrder": 2,
"totalResponses": 4100,
"skippedCount": 100,
"responseRate": 97.6,
"options": [
{ "key": "find_job", "label": "Find a Job", "count": 2460, "percentage": 60.0 },
{ "key": "start_business", "label": "Start Business", "count": 1845, "percentage": 45.0 },
{ "key": "learn_skills", "label": "Learn Skills", "count": 1640, "percentage": 40.0 },
{ "key": "get_funding", "label": "Get Funding", "count": 1230, "percentage": 30.0 }
]
},
{
"pageId": "550e8400-e29b-41d4-a716-446655440003",
"categoryKey": "experience",
"title": "Your Experience",
"pageOrder": 3,
"totalResponses": 4050,
"skippedCount": 150,
"responseRate": 96.4,
"options": [
{ "key": "student", "label": "Student", "count": 1215, "percentage": 30.0 },
{ "key": "0-2_years", "label": "0-2 Years", "count": 1012, "percentage": 25.0 },
{ "key": "3-5_years", "label": "3-5 Years", "count": 810, "percentage": 20.0 },
{ "key": "5+_years", "label": "5+ Years", "count": 607, "percentage": 15.0 },
{ "key": "business_owner", "label": "Business Owner", "count": 405, "percentage": 10.0 }
]
}
]
}
}
Success Response Fields:
| Field | Description |
|---|---|
| totalUsersAnalyzed | Users who responded to at least one page |
| generatedAt | Timestamp when data was generated |
| pages[].totalResponses | Users who responded to this page |
| pages[].skippedCount | Users who skipped this page |
| pages[].responseRate | Percentage of users who responded |
| pages[].options[].count | Number of users who selected this option |
| pages[].options[].percentage | Percentage of respondents who selected this option |
3. Get Page Analytics
Purpose: Get detailed analytics for a specific preference page.
Endpoint: GET {base_url}/onboarding/analytics/page/{pageId}
Access Level: 🔒 Protected (Admin Only)
Authentication: Bearer Token
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| pageId | UUID | Yes | Page identifier |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Page analytics retrieved",
"action_time": "2025-01-05T14:10:00",
"data": {
"pageId": "550e8400-e29b-41d4-a716-446655440001",
"categoryKey": "interests",
"title": "Your Interests",
"pageOrder": 1,
"totalResponses": 4200,
"skippedCount": 0,
"responseRate": 100.0,
"options": [
{ "key": "jobs", "label": "Jobs", "count": 2520, "percentage": 60.0 },
{ "key": "funding", "label": "Funding", "count": 1890, "percentage": 45.0 }
]
}
}
4. Get Page Analytics by Category
Purpose: Get analytics for a page using category key instead of UUID.
Endpoint: GET {base_url}/onboarding/analytics/category/{categoryKey}
Access Level: 🔒 Protected (Admin Only)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| categoryKey | string | Yes | Page category key (e.g., "interests", "goals") |
Success Response: Same as Get Page Analytics
5. Get User Demographics
Purpose: Get all preference selections for a specific user.
Endpoint: GET {base_url}/onboarding/analytics/user/{userId}
Access Level: 🔒 Protected (Admin Only)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| userId | UUID | Yes | User identifier |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "User demographics retrieved",
"action_time": "2025-01-05T14:15:00",
"data": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"preferences": {
"interests": ["jobs", "funding", "skills"],
"goals": ["find_job", "learn_skills"],
"experience": ["3-5_years"]
}
}
}
6. Get Users by Selection
Purpose: Find all users who selected a specific option in a category.
Endpoint: GET {base_url}/onboarding/analytics/users/by-selection
Access Level: 🔒 Protected (Admin Only)
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| categoryKey | string | Yes | Page category (e.g., "interests") |
| optionKey | string | Yes | Option key (e.g., "jobs") |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Users retrieved",
"action_time": "2025-01-05T14:20:00",
"data": {
"categoryKey": "interests",
"optionKey": "jobs",
"count": 2520,
"userIds": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]
}
}
7. Get Most Popular Options
Purpose: Get top selected options for a category.
Endpoint: GET {base_url}/onboarding/analytics/popular-options/{categoryKey}
Access Level: 🔒 Protected (Admin Only)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| categoryKey | string | Yes | Page category |
Query Parameters:
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
| limit | integer | No | Max results to return | 10 |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Popular options retrieved",
"action_time": "2025-01-05T14:25:00",
"data": {
"categoryKey": "interests",
"options": ["jobs", "funding", "skills", "events", "networking"]
}
}
8. Get Similar Users
Purpose: Find users with similar preferences (for recommendation testing).
Endpoint: GET {base_url}/onboarding/analytics/user/{userId}/similar
Access Level: 🔒 Protected (Admin Only)
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| userId | UUID | Yes | Reference user |
Query Parameters:
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
| limit | integer | No | Max similar users to return | 10 |
Success Response JSON Sample:
{
"success": true,
"httpStatus": "OK",
"message": "Similar users retrieved",
"action_time": "2025-01-05T14:30:00",
"data": {
"userId": "550e8400-e29b-41d4-a716-446655440000",
"similarUsers": [
"550e8400-e29b-41d4-a716-446655440010",
"550e8400-e29b-41d4-a716-446655440011",
"550e8400-e29b-41d4-a716-446655440012"
],
"count": 3
}
}
Internal Service Methods
These methods are available in OnboardingAnalyticsService for use by other backend services (recommendation engine, social media features, etc.):
// Get user's selections for a specific category
List<String> getUserSelections(UUID userId, String categoryKey);
// Example: getUserSelections(userId, "interests") → ["jobs", "funding"]
// Get complete user demographics
UserDemographicDto getUserDemographics(UUID userId);
// Returns all preferences across all categories
// Find users who selected specific option
List<UUID> getUsersBySelection(String categoryKey, String optionKey);
// Example: getUsersBySelection("goals", "start_business") → [userId1, userId2, ...]
// Find users who selected any of multiple options
List<UUID> getUsersBySelections(String categoryKey, List<String> optionKeys);
// Check if user selected a specific option
boolean hasUserSelected(UUID userId, String categoryKey, String optionKey);
// Example: hasUserSelected(userId, "interests", "jobs") → true
// Find users with similar preferences (for recommendations)
List<UUID> getUsersWithSimilarPreferences(UUID userId, int limit);
// Get most popular options in a category
List<String> getMostPopularOptions(String categoryKey, int limit);
Admin Dashboard Usage
Summary Cards
GET /onboarding/analytics/summary
├── Card 1: Total Users (totalUsers)
├── Card 2: Completion Rate (completionRate%)
├── Card 3: Active Today (calculate from other data)
└── Card 4: Pending Verification (byStatus.PENDING_*)
Pie Charts
GET /onboarding/analytics/summary
├── Chart 1: Users by Auth Provider (byAuthProvider)
├── Chart 2: Users by Language (byLanguage)
└── Chart 3: Users by Theme (byTheme)
Demographics Bar Charts
GET /onboarding/analytics/demographics
For each page:
├── Chart: Option distribution
├── Show percentage bars
└── Highlight top selections
User Lookup
GET /onboarding/analytics/user/{userId}
├── Show all user preferences
├── Link to full profile
└── Show similar users