​
Overview

The Wellbeing API manages employee wellbeing surveys with a strict 12 surveys per user per year limit. Surveys include AI-powered sentiment analysis and risk level assessment to identify employees needing support.

​
Rate Limiting

Critical Business Rule: Users can submit a maximum of 12 wellbeing surveys per calendar year.
  • Attempts beyond the limit return 429 Too Many Requests
  • Limit resets annually on January 1st
  • Emergency override available for crisis situations

​
Endpoints

​
Submit Survey

POST /api/wellbeing/survey Submit a wellbeing survey response. Request Body: 
{
  "responses": {
    "stress_level": 7,
    "work_life_balance": 5,
    "support_from_colleagues": 8,
    "mental_health_days_used": 2,
    "overall_satisfaction": 6,
    "comments": "Feeling overwhelmed with current workload"
  }
}
AI Processing:
  • Automatic sentiment analysis (positive/neutral/negative)
  • Risk level assessment (low/medium/high)
  • Keyword extraction for support needs

​
List Surveys

GET /api/wellbeing/surveys Retrieve survey history (user’s own or admin access). Query Parameters:
  • userId: Filter by specific user (admin only)

​
Check Eligibility

GET /api/wellbeing/eligibility Check if user can submit another survey. Response: 
{
  "data": {
    "canSubmit": true,
    "surveysThisYear": 8,
    "nextEligibleDate": "2024-12-31T23:59:59Z"
  }
}

​
Get Statistics

GET /api/wellbeing/stats Retrieve aggregated wellbeing statistics. Response: 
{
  "data": {
    "totalSurveys": 1247,
    "averageSentiment": "neutral",
    "riskDistribution": {
      "low": 892,
      "medium": 289,
      "high": 66
    },
    "recentSurveys": 156,
    "sentimentTrend": [
      {
        "month": "2024-01",
        "positive": 45,
        "neutral": 32,
        "negative": 12
      }
    ]
  }
}

​
Survey Structure

​
Standard Questions

Surveys typically include 8-12 standardized questions:
  1. Stress Level (1-10 scale)
  2. Work-Life Balance (1-10 scale)
  3. Support from Colleagues (1-10 scale)
  4. Mental Health Resources Used (count)
  5. Overall Job Satisfaction (1-10 scale)
  6. Open Comments (optional text)

​
Custom Questions

Organizations can configure additional custom questions: 
{
  "responses": {
    "standard_questions": { /* ... */ },
    "custom_department_satisfaction": 7,
    "custom_remote_work_preference": "hybrid"
  }
}

​
AI Analysis

​
Sentiment Analysis

  • Positive: Scores 7-10, supportive language
  • Neutral: Scores 4-6, balanced feedback
  • Negative: Scores 1-3, concerning language

​
Risk Assessment

  • Low Risk: Consistent positive scores, no concerning keywords
  • Medium Risk: Mixed scores, occasional stress indicators
  • High Risk: Low scores, crisis keywords (burnout, depression, suicidal)

​
Automated Alerts

  • High-risk surveys trigger immediate HR notifications
  • Medium-risk surveys flagged for follow-up
  • Crisis keywords trigger emergency protocols

​
Business Rules

  • Annual Limit: 12 surveys maximum per user per year
  • Emergency Override: Crisis situations can bypass limit
  • Confidentiality: Surveys anonymized for aggregate reporting
  • AI Fallback: Sentiment analysis falls back to neutral if AI unavailable
  • Retention: Survey data retained for 7 years for compliance

​
Privacy & Compliance

​
Data Protection

  • Surveys stored encrypted at rest
  • PII automatically redacted from comments
  • Access restricted to HR and employee themselves
  • Audit trail for all survey access

​
Compliance

  • GDPR compliant data processing
  • HIPAA equivalent protections for mental health data
  • Regular security audits and penetration testing

​
Response Examples

Successful Survey Submission: 
{
  "data": {
    "id": "survey-uuid",
    "userId": "user-uuid",
    "organizationId": "org-uuid",
    "responses": {
      "stress_level": 7,
      "work_life_balance": 5,
      "comments": "Feeling overwhelmed with current workload"
    },
    "sentiment": "negative",
    "riskLevel": "medium",
    "createdAt": "2024-01-15T14:30:00Z"
  }
}
Rate Limit Exceeded: 
{
  "error": "Survey limit reached",
  "details": {
    "surveysThisYear": 12,
    "nextEligibleDate": "2025-01-01T00:00:00Z"
  }
}
Eligibility Check: 
{
  "data": {
    "canSubmit": false,
    "surveysThisYear": 12,
    "nextEligibleDate": "2025-01-01T00:00:00Z"
  }
}