Smart Alerts

Get Alerts

Retrieve smart alerts generated by the AI-powered pattern detection system. Alerts are automatically created when concerning patterns are detected, such as high turnover risk, burnout indicators, or negative sentiment trends.

GET /api/diagnostic/alerts

Authentication

Requires authentication and admin role authorization.

Query Parameters

status

string

default:"nueva"

Filter alerts by status. Possible values:

nueva - New, unviewed alerts (default)
en_proceso - Alerts being actively addressed
resuelta - Resolved alerts
descartada - Dismissed alerts

limit

number

default:"20"

Maximum number of alerts to return (default: 20)

Request Example

curl -X GET "https://api.cuido.com/api/diagnostic/alerts?status=nueva&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

success

boolean

Indicates if the request was successful

message

string

Response message

data

object

Response data object

Show data fields

data.alerts

array

Array of SmartAlert objects

Show alert fields

_id

string

Unique alert identifier

employeeId

object

Populated employee information

personalInfo.name: Employee name
jobInfo.position: Job position
jobInfo.department: Department

type

string

Alert type classification:

riesgo_rotacion - Turnover risk
burnout_detectado - Burnout detected
bajo_rendimiento - Low performance
falta_participacion - Lack of participation
sentimiento_negativo - Negative sentiment
sobrecarga_trabajo - Work overload
falta_apoyo_equipo - Lack of team support

severity

string

Alert severity level:

baja - Low severity
media - Medium severity
alta - High severity
critica - Critical severity (auto-escalated)

description

string

Human-readable description of the detected issue

triggerData

object

Metadata about what triggered the alert

Show triggerData fields

triggerData.pattern

string

Pattern type that triggered the alert (e.g., “encuesta_alto_riesgo”, “patron_riesgo_continuo”, “tendencia_riesgo_creciente”)

triggerData.metrics

object

Relevant metrics that triggered the alert (structure varies by alert type)

triggerData.timeframe

string

Time period analyzed (e.g., “actual”, “últimas_3_semanas”, “últimas_2_semanas”)

triggerData.confidence

number

Confidence score (0-1) indicating reliability of the pattern detection

recommendations

array

Array of actionable recommendations

Show recommendation fields

action

string

Recommended action to address the issue

priority

string

Priority level: baja, media, or alta

estimatedImpact

string

Expected impact of taking this action

assignedTo

object

Suggested responsible party

role: Recommended role (e.g., “supervisor”, “rh”, “admin”, “mentor”)
department: Relevant department (if applicable)

status

string

Current status: nueva, en_proceso, resuelta, or descartada

escalated

boolean

Whether the alert has been escalated to higher management

createdAt

string

ISO 8601 timestamp when alert was created

Response Example

{
  "success": true,
  "message": "Alertas obtenidas exitosamente",
  "data": {
    "alerts": [
      {
        "_id": "507f1f77bcf86cd799439015",
        "employeeId": {
          "_id": "507f1f77bcf86cd799439011",
          "personalInfo": {
            "name": "Dr. María González"
          },
          "jobInfo": {
            "position": "Enfermera",
            "department": "urgencias"
          }
        },
        "type": "riesgo_rotacion",
        "severity": "alta",
        "description": "Empleado Dr. María González presenta riesgo alto de rotación (78%)",
        "triggerData": {
          "pattern": "encuesta_alto_riesgo",
          "metrics": {
            "riskScore": 78,
            "riskLevel": "alto",
            "factors": {
              "moodToday": 0.3,
              "workloadLevel": 0.2,
              "teamSupport": 0.4,
              "jobSatisfaction": 0.3
            },
            "adjustments": 1.15
          },
          "timeframe": "actual",
          "confidence": 0.8
        },
        "recommendations": [
          {
            "action": "Programar entrevista individual con supervisor",
            "priority": "alta",
            "estimatedImpact": "Identificar causas específicas del malestar",
            "assignedTo": {
              "role": "supervisor",
              "department": "urgencias"
            }
          },
          {
            "action": "Evaluar carga de trabajo actual",
            "priority": "media",
            "estimatedImpact": "Reducir estrés laboral",
            "assignedTo": {
              "role": "rh",
              "department": "urgencias"
            }
          }
        ],
        "status": "nueva",
        "escalated": false,
        "createdAt": "2026-03-05T09:15:00.000Z"
      },
      {
        "_id": "507f1f77bcf86cd799439016",
        "employeeId": {
          "_id": "507f1f77bcf86cd799439012",
          "personalInfo": {
            "name": "Lic. Carlos Mendoza"
          },
          "jobInfo": {
            "position": "Médico General",
            "department": "hospitalizacion"
          }
        },
        "type": "sentimiento_negativo",
        "severity": "media",
        "description": "Tendencia creciente de riesgo detectada en Lic. Carlos Mendoza",
        "triggerData": {
          "pattern": "tendencia_riesgo_creciente",
          "metrics": {
            "riskScores": [45, 52, 58, 65],
            "trend": "creciente"
          },
          "confidence": 0.75
        },
        "recommendations": [
          {
            "action": "Monitoreo semanal intensivo",
            "priority": "alta",
            "assignedTo": {
              "role": "supervisor"
            }
          },
          {
            "action": "Identificar factores de estrés recientes",
            "priority": "media",
            "assignedTo": {
              "role": "rh"
            }
          }
        ],
        "status": "nueva",
        "escalated": false,
        "createdAt": "2026-03-05T08:45:00.000Z"
      }
    ]
  }
}

Mark Alert as Viewed

Update an alert’s status to indicate it has been reviewed by an administrator.

PUT /api/diagnostic/alerts/:id/view

Authentication

Requires authentication and admin role authorization.

Path Parameters

string

required

Unique identifier of the alert to mark as viewed

Request Example

curl -X PUT "https://api.cuido.com/api/diagnostic/alerts/507f1f77bcf86cd799439015/view" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

success

boolean

Indicates if the request was successful

message

string

Response message

data

object

Response data object containing the updated alert

Show data fields

data.alert

object

Updated alert object with status changed to vista and viewedAt timestamp set

Response Example

{
  "success": true,
  "message": "Alerta marcada como vista",
  "data": {
    "alert": {
      "_id": "507f1f77bcf86cd799439015",
      "employeeId": "507f1f77bcf86cd799439011",
      "type": "riesgo_rotacion",
      "severity": "alta",
      "status": "vista",
      "viewedAt": "2026-03-05T10:30:00.000Z",
      "createdAt": "2026-03-05T09:15:00.000Z"
    }
  }
}

Alert Generation Patterns

SmartAlerts are automatically generated by analyzing multiple data sources. The system detects the following patterns:

1. High Risk Survey

Triggered when a single survey shows high risk (score ≥ 70). Implementation: diagnosticService.js:402-434 Recommendations:

Schedule individual interview with supervisor
Evaluate current workload

2. Continuous Risk Pattern

Triggered when an employee has 3+ medium/high risk surveys in the last 3 weeks. Implementation: diagnosticService.js:541-582 Recommendations:

Immediate intervention with direct supervisor
Occupational psychological evaluation

3. Increasing Risk Trend

Triggered when risk scores show an upward trend over 2+ weeks. Implementation: diagnosticService.js:771-833 Recommendations:

Intensive weekly monitoring
Identify recent stress factors

4. Negative Sentiment Pattern

Triggered when AI text analysis detects 2+ negative sentiments with high risk scores (≥60) in 2 weeks. Implementation: diagnosticService.js:631-667 Recommendations:

Individual emotional support session
Review workplace stress factors

5. Low Participation (Department-Level)

Triggered when department participation falls below 30% in the last week. Implementation: diagnosticService.js:585-629 Recommendations:

Awareness campaign about survey importance
Review platform accessibility

The system runs pattern detection automatically after each survey is processed and can also be triggered manually via scheduled jobs.

Auto-Escalation

Alerts with severity: "critica" are automatically escalated to higher management. Implementation: smartAlertSchema.methods.autoEscalate() in models/SmartAlert.js:90-99 When auto-escalated:

escalated flag is set to true
Entry added to escalationHistory with reason “Escalación automática por severidad crítica”
Escalated to “direccion_medica” (medical director)

Confidence Scores

Each alert includes a confidence score (0-1) indicating the reliability of the pattern detection:

0.9: Very high confidence (e.g., low participation with clear metrics)
0.8-0.85: High confidence (e.g., sentiment analysis, risk patterns)
0.75: Medium-high confidence (e.g., trend detection with limited data points)

Lower confidence scores may warrant additional validation before taking action.

Recommendation Assignment

Recommendations are automatically assigned to roles based on the action category:

Category	Assigned Role
Emotional support	mentor
Training	rh (Human Resources)
Recognition	supervisor
Mentoring	mentor
Rest/time off	supervisor

See mapping in diagnosticService.js:874-883.

Use Cases

Proactive Intervention: Address employee issues before turnover occurs
Resource Prioritization: Focus HR efforts on highest-risk employees
Pattern Recognition: Identify systemic issues affecting multiple employees
Compliance: Document wellness monitoring and intervention efforts
Analytics: Track alert resolution effectiveness over time

Quick Survey - Submit surveys that may generate alerts
Wellness Heatmap - View department-level wellness overview

Authentication

Employees

Diagnostic Module

Mentorship Module

Microlearning Module

Recognition Module

Correlation Module

Chat & Prompts

Get Alerts

Authentication

Query Parameters

Request Example

Response

Response Example

Mark Alert as Viewed

Authentication

Path Parameters

Request Example

Response

Response Example

Alert Generation Patterns

1. High Risk Survey

2. Continuous Risk Pattern

3. Increasing Risk Trend

4. Negative Sentiment Pattern

5. Low Participation (Department-Level)

Auto-Escalation

Confidence Scores

Recommendation Assignment

Use Cases

Build docs developers (and LLMs) love

Authentication

Employees

Diagnostic Module

Mentorship Module

Microlearning Module

Recognition Module

Correlation Module

Chat & Prompts

​Get Alerts

​Authentication

​Query Parameters

​Request Example

​Response

​Response Example

​Mark Alert as Viewed

​Authentication

​Path Parameters

​Request Example

​Response

​Response Example

​Alert Generation Patterns

​1. High Risk Survey

​2. Continuous Risk Pattern

​3. Increasing Risk Trend

​4. Negative Sentiment Pattern

​5. Low Participation (Department-Level)

​Auto-Escalation

​Confidence Scores

​Recommendation Assignment

​Use Cases

​Related Endpoints

Build docs developers (and LLMs) love

Get Alerts

Authentication

Query Parameters

Request Example

Response

Response Example

Mark Alert as Viewed

Authentication

Path Parameters

Request Example

Response

Response Example

Alert Generation Patterns

1. High Risk Survey

2. Continuous Risk Pattern

3. Increasing Risk Trend

4. Negative Sentiment Pattern

5. Low Participation (Department-Level)

Auto-Escalation

Confidence Scores

Recommendation Assignment

Use Cases

Related Endpoints