Supervisor API
The Supervisor API provides endpoints for supervisors to manage and review the chat logs and activities of the employees they supervise. This functionality is crucial for regulatory compliance in financial services, allowing supervisors to monitor communications, review AI interactions, and ensure proper usage of the system.
Regulatory Compliance: Supervisory review is a regulatory requirement for many financial services communications. This API ensures supervisors can fulfill their oversight responsibilities while maintaining audit trails of all supervisory activities.
Supervisor Features
👥 Team Management
View and manage all supervised users, their roles, activity levels, and performance metrics.
💬 Chat Oversight
Review all chat conversations of supervised users, including AI responses and user interactions.
🚨 Compliance Monitoring
Monitor compliance flags and violations for supervised users, with detailed review capabilities.
📊 Activity Analytics
Detailed analytics on supervised user activity, usage patterns, and productivity metrics.
📋 Review Workflows
Structured review processes for flagged content, with approval workflows and documentation.
🔍 Audit Trails
Complete audit logs of all supervisory activities and decisions for regulatory compliance.
Get Supervised Team
Get a list of users that are supervised by the authenticated user, including their activity summary and recent status.
GET
/api/v1/supervisor/team
Authentication:
Required
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 20, max: 100) |
| search | string | No | Search term to filter users by name or email |
| status | string | No | Filter by user status (active, inactive, suspended) |
| department | string | No | Filter by department |
| role_id | integer | No | Filter by role ID |
| include_stats | boolean | No | Include activity statistics (default: true) |
| sort_by | string | No | Sort by field (name, last_login, activity_level, compliance_flags) |
| sort_order | string | No | Sort order (asc, desc) |
Example Response
{
"success": true,
"data": {
"supervised_users": [
{
"id": 123,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com",
"status": "active",
"role": {
"id": 3,
"name": "Financial Advisor",
"key": "financial_advisor"
},
"department": "Investment Management",
"employee_id": "EMP001123",
"profile_image_url": "https://oliverchat.com/storage/profile-images/user_123.jpg",
"last_login": "2025-03-11T08:30:00Z",
"activity_summary": {
"total_chats": 156,
"total_messages": 1247,
"images_generated": 23,
"compliance_flags": 2,
"resolved_flags": 2,
"last_activity": "2025-03-11T08:35:00Z",
"activity_level": "high",
"avg_session_duration_minutes": 18.5
},
"compliance_status": {
"active_flags": 0,
"total_flags": 2,
"last_flag_date": "2025-02-28T14:20:00Z",
"requires_attention": false
},
"supervision_notes": {
"last_review_date": "2025-03-01T10:00:00Z",
"next_review_due": "2025-03-15T10:00:00Z",
"review_frequency": "bi_weekly"
}
},
{
"id": 124,
"name": "Jane Doe",
"email": "jdoe@advisorsassetmanagement.com",
"status": "active",
"role": {
"id": 3,
"name": "Financial Advisor",
"key": "financial_advisor"
},
"department": "Investment Management",
"employee_id": "EMP001124",
"profile_image_url": null,
"last_login": "2025-03-10T16:45:00Z",
"activity_summary": {
"total_chats": 89,
"total_messages": 672,
"images_generated": 12,
"compliance_flags": 1,
"resolved_flags": 0,
"last_activity": "2025-03-10T17:20:00Z",
"activity_level": "medium",
"avg_session_duration_minutes": 14.2
},
"compliance_status": {
"active_flags": 1,
"total_flags": 1,
"last_flag_date": "2025-03-09T11:30:00Z",
"requires_attention": true
},
"supervision_notes": {
"last_review_date": "2025-02-28T15:30:00Z",
"next_review_due": "2025-03-14T15:30:00Z",
"review_frequency": "bi_weekly"
}
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 2,
"total_pages": 1
},
"team_summary": {
"total_supervised_users": 2,
"active_users": 2,
"inactive_users": 0,
"users_requiring_attention": 1,
"total_compliance_flags": 1,
"overdue_reviews": 0,
"high_activity_users": 1,
"low_activity_users": 0
}
},
"message": "Supervised team retrieved successfully"
}Get User's Chats
Get a list of chat conversations for a specific supervised user, including recent activity and compliance status.
GET
/api/v1/supervisor/users/{user_id}/chats
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_id | integer | Yes | ID of the supervised user |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 20, max: 100) |
| date_from | string | No | Filter chats from date (ISO 8601 format) |
| date_to | string | No | Filter chats to date (ISO 8601 format) |
| has_flags | boolean | No | Filter chats with compliance flags |
| is_private | boolean | No | Filter by private/public chat status |
| include_messages | boolean | No | Include recent messages in response (default: false) |
Example Response
{
"success": true,
"data": {
"user": {
"id": 123,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com",
"role": "Financial Advisor"
},
"chats": [
{
"id": "chat_123456789",
"name": "Portfolio Review Discussion",
"is_private": false,
"message_count": 25,
"created_at": "2025-03-10T09:15:00Z",
"last_message_at": "2025-03-11T08:35:00Z",
"compliance_flags": [
{
"id": 12345,
"severity": "medium",
"category": "communication_standards",
"status": "resolved",
"flagged_at": "2025-03-10T10:30:00Z"
}
],
"rag_containers_used": [
{
"id": 1,
"name": "Financial Regulations",
"category": "regulatory"
}
],
"images_generated": 2,
"attachments_count": 1,
"summary": {
"total_user_messages": 13,
"total_ai_responses": 12,
"session_duration_minutes": 22,
"topics_discussed": ["portfolio review", "risk assessment", "regulatory compliance"]
}
},
{
"id": "chat_123456790",
"name": "Client Investment Strategy",
"is_private": true,
"message_count": 18,
"created_at": "2025-03-09T14:20:00Z",
"last_message_at": "2025-03-09T15:45:00Z",
"compliance_flags": [],
"rag_containers_used": [
{
"id": 2,
"name": "Investment Strategies",
"category": "investment"
}
],
"images_generated": 1,
"attachments_count": 0,
"summary": {
"total_user_messages": 9,
"total_ai_responses": 9,
"session_duration_minutes": 85,
"topics_discussed": ["investment strategy", "client suitability", "risk tolerance"]
}
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 2,
"total_pages": 1
},
"summary": {
"total_chats": 2,
"chats_with_flags": 1,
"private_chats": 1,
"public_chats": 1,
"total_messages": 43,
"total_compliance_flags": 1,
"date_range": {
"earliest_chat": "2025-03-09T14:20:00Z",
"latest_activity": "2025-03-11T08:35:00Z"
}
}
},
"message": "User chats retrieved successfully"
}Get Chat Details
Get detailed information about a specific chat conversation, including all messages and compliance analysis.
GET
/api/v1/supervisor/chats/{chat_id}
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| chat_id | string | Yes | ID of the chat conversation |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| include_attachments | boolean | No | Include attachment information (default: true) |
| include_images | boolean | No | Include generated images (default: true) |
| include_citations | boolean | No | Include RAG citations (default: true) |
Example Response
{
"success": true,
"data": {
"chat": {
"id": "chat_123456789",
"name": "Portfolio Review Discussion",
"user": {
"id": 123,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com",
"role": "Financial Advisor"
},
"created_at": "2025-03-10T09:15:00Z",
"last_message_at": "2025-03-11T08:35:00Z",
"is_private": false,
"compliance_status": {
"total_flags": 1,
"active_flags": 0,
"resolved_flags": 1,
"last_review_date": "2025-03-10T16:00:00Z",
"reviewed_by": {
"id": 15,
"name": "Sarah Wilson",
"role": "Compliance Officer"
}
},
"messages": [
{
"id": "msg_987654321",
"role": "user",
"content": "I need to review my client's portfolio allocation. Can you help me analyze the current mix?",
"timestamp": "2025-03-10T09:16:00Z",
"attachments": [
{
"id": "file_123456789",
"filename": "client_portfolio.pdf",
"mime_type": "application/pdf",
"file_size": 1024576
}
],
"compliance_flags": []
},
{
"id": "msg_987654322",
"role": "assistant",
"content": "I'll help you analyze your client's portfolio allocation. Based on the document you've shared, I can see the current asset mix and provide insights on diversification and risk assessment.",
"timestamp": "2025-03-10T09:16:30Z",
"citations": [
{
"source": "Financial Regulations",
"document": "SEC Rule 10b-5",
"relevance_score": 0.89
}
],
"compliance_flags": []
},
{
"id": "msg_987654323",
"role": "user",
"content": "This investment will definitely make the client rich quickly with guaranteed returns.",
"timestamp": "2025-03-10T09:18:00Z",
"attachments": [],
"compliance_flags": [
{
"id": 12345,
"violation_type": "inappropriate_language",
"severity": "medium",
"status": "resolved",
"flagged_content": "definitely make the client rich quickly with guaranteed returns",
"violation_reason": "Misleading investment promise - violates FINRA Rule 2210",
"flagged_at": "2025-03-10T09:18:05Z",
"resolved_at": "2025-03-10T16:00:00Z",
"resolution_notes": "Discussed with advisor about appropriate language for client communications"
}
]
}
],
"generated_images": [
{
"id": "img_123456789",
"url": "https://oliverchat.com/storage/generated-images/img_123456789.png",
"prompt": "Portfolio allocation pie chart",
"generated_at": "2025-03-10T09:20:00Z"
}
],
"rag_usage": {
"containers_accessed": [
{
"id": 1,
"name": "Financial Regulations",
"queries": 3,
"documents_referenced": 2
}
],
"total_citations": 5,
"confidence_scores": [0.89, 0.76, 0.82, 0.91, 0.73]
},
"session_analytics": {
"total_messages": 25,
"user_messages": 13,
"ai_responses": 12,
"session_duration_minutes": 22,
"average_response_time_seconds": 2.1,
"topics_discussed": ["portfolio review", "risk assessment", "regulatory compliance"],
"engagement_score": 8.5
}
},
"supervisor_notes": {
"last_review_date": "2025-03-10T16:00:00Z",
"review_status": "approved",
"reviewer_notes": "Chat reviewed and compliance issue resolved. Advisor provided additional training on appropriate language.",
"next_review_required": false
}
},
"message": "Chat details retrieved successfully"
}Get Team Compliance Flags
Get all compliance flags for the supervisor's team, with filtering and review capabilities.
GET
/api/v1/supervisor/compliance-flags
Authentication:
Required
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 20, max: 100) |
| user_id | integer | No | Filter by specific supervised user |
| severity | string | No | Filter by severity (low, medium, high, critical) |
| status | string | No | Filter by status (active, resolved, dismissed) |
| category | string | No | Filter by violation category |
| date_from | string | No | Start date filter (ISO 8601 format) |
| date_to | string | No | End date filter (ISO 8601 format) |
| requires_attention | boolean | No | Filter flags requiring supervisory attention |
Example Response
{
"success": true,
"data": {
"compliance_flags": [
{
"id": 12345,
"user": {
"id": 123,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com",
"role": "Financial Advisor"
},
"chat_id": "chat_123456789",
"message_id": "msg_987654323",
"violation_type": "inappropriate_language",
"category": "communication_standards",
"severity": "medium",
"status": "resolved",
"flagged_content": "This investment will definitely make the client rich quickly with guaranteed returns.",
"violation_reason": "Misleading investment promise - violates FINRA Rule 2210",
"flagged_at": "2025-03-10T09:18:05Z",
"reviewed_at": "2025-03-10T16:00:00Z",
"resolved_at": "2025-03-10T16:00:00Z",
"reviewer": {
"id": 15,
"name": "Sarah Wilson",
"role": "Compliance Officer"
},
"resolution_notes": "Discussed with advisor about appropriate language for client communications. Additional training provided.",
"supervisor_action_required": false,
"escalation_level": 1,
"metadata": {
"confidence_score": 0.89,
"rule_references": ["FINRA 2210"],
"similar_violations": 3
}
},
{
"id": 12346,
"user": {
"id": 124,
"name": "Jane Doe",
"email": "jdoe@advisorsassetmanagement.com",
"role": "Financial Advisor"
},
"chat_id": "chat_123456790",
"message_id": "msg_987654324",
"violation_type": "client_data_exposure",
"category": "data_privacy",
"severity": "high",
"status": "active",
"flagged_content": "Client John Doe (SSN: 123-45-6789) needs immediate portfolio adjustment",
"violation_reason": "Potential PII exposure in chat message",
"flagged_at": "2025-03-09T11:30:00Z",
"reviewed_at": null,
"resolved_at": null,
"reviewer": null,
"resolution_notes": null,
"supervisor_action_required": true,
"escalation_level": 2,
"metadata": {
"confidence_score": 0.95,
"data_types_detected": ["ssn", "name"],
"auto_masked": true
}
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 2,
"total_pages": 1
},
"summary": {
"total_flags": 2,
"active_flags": 1,
"resolved_flags": 1,
"flags_requiring_attention": 1,
"high_severity_flags": 1,
"flags_by_user": {
"123": 1,
"124": 1
},
"flags_by_category": {
"communication_standards": 1,
"data_privacy": 1
}
}
},
"message": "Team compliance flags retrieved successfully"
}Review Compliance Flag
Review and provide action on a compliance flag for a supervised user.
PUT
/api/v1/supervisor/compliance-flags/{flag_id}/review
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| flag_id | integer | Yes | ID of the compliance flag to review |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | Review action (approve, escalate, require_training, dismiss) |
| notes | string | Yes | Supervisor review notes |
| training_required | boolean | No | Whether employee training is required |
| training_type | string | No | Type of training required (compliance, communication, technical) |
| follow_up_date | string | No | Date for follow-up review (ISO 8601 format) |
| escalate_to | integer | No | User ID to escalate to (required if action is "escalate") |
Example Request
{
"action": "require_training",
"notes": "Employee used inappropriate language that could mislead clients. Immediate training required on FINRA communication standards.",
"training_required": true,
"training_type": "compliance",
"follow_up_date": "2025-03-18T10:00:00Z"
}Example Response
{
"success": true,
"data": {
"flag": {
"id": 12345,
"status": "under_supervisor_review",
"supervisor_review": {
"action": "require_training",
"notes": "Employee used inappropriate language that could mislead clients. Immediate training required on FINRA communication standards.",
"reviewed_by": {
"id": 45,
"name": "Mary Johnson",
"role": "Senior Supervisor"
},
"reviewed_at": "2025-03-11T17:30:00Z",
"training_required": true,
"training_type": "compliance",
"follow_up_date": "2025-03-18T10:00:00Z"
}
},
"actions_taken": {
"training_scheduled": true,
"user_notified": true,
"compliance_team_notified": true,
"follow_up_reminder_set": true
}
},
"message": "Compliance flag reviewed successfully"
}Generate Team Activity Report
Generate a comprehensive activity report for the supervised team, including usage analytics and compliance summary.
POST
/api/v1/supervisor/reports/activity
Authentication:
Required
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| date_from | string | Yes | Start date for report period (ISO 8601 format) |
| date_to | string | Yes | End date for report period (ISO 8601 format) |
| user_ids | array | No | Specific user IDs to include (default: all supervised users) |
| include_compliance | boolean | No | Include compliance analysis (default: true) |
| include_performance | boolean | No | Include performance metrics (default: true) |
| format | string | No | Report format (pdf, excel, json) |
Example Request
{
"date_from": "2025-02-01T00:00:00Z",
"date_to": "2025-02-28T23:59:59Z",
"include_compliance": true,
"include_performance": true,
"format": "pdf"
}Example Response
{
"success": true,
"data": {
"report": {
"id": "report_supervisor_123456789",
"type": "team_activity",
"period": {
"from": "2025-02-01T00:00:00Z",
"to": "2025-02-28T23:59:59Z"
},
"supervisor": {
"id": 45,
"name": "Mary Johnson",
"email": "mjohnson@advisorsassetmanagement.com"
},
"team_summary": {
"supervised_users": 15,
"active_users": 14,
"total_chats": 234,
"total_messages": 1876,
"images_generated": 89,
"compliance_flags": 7,
"resolved_flags": 6,
"training_sessions_completed": 12
},
"performance_metrics": {
"average_session_duration": 19.3,
"average_messages_per_chat": 8.0,
"high_performers": 5,
"needs_attention": 2,
"productivity_score": 8.2
},
"compliance_summary": {
"total_violations": 7,
"critical_violations": 0,
"high_severity": 1,
"medium_severity": 4,
"low_severity": 2,
"resolution_rate": 85.7,
"average_resolution_time_hours": 4.2
},
"download_url": "https://oliverchat.com/storage/supervisor-reports/report_supervisor_123456789.pdf",
"expires_at": "2025-03-18T17:45:00Z",
"generated_at": "2025-03-11T17:45:00Z"
}
},
"message": "Team activity report generated successfully"
}Supervisory Best Practices
Regulatory Guidance: Regular supervisory review is essential for compliance with financial services regulations. We recommend:
- Weekly review of all supervised user activity
- Immediate review of any compliance flags
- Monthly comprehensive team reports for management
- Quarterly training assessments and updates
- Annual review of supervisory procedures and effectiveness
API Tester
Test the Supervisor API endpoints directly from this documentation.