# COMPASS API Documentation ## Docs - [Logout](https://compass.docs.sunnyscoach.com/auth/logout.md): Logs out the currently authenticated user by invalidating their session token. Requires a valid authentication token. After calling this endpoint remove the user data from the client. - [Google OAuth Sign-in](https://compass.docs.sunnyscoach.com/auth/signin-google.md): Exchange Google OAuth authorization code for user profile and issue a session token. If the user does not exist, a new user is created. - [Microsoft OAuth Sign-in](https://compass.docs.sunnyscoach.com/auth/signin-microsoft.md): Exchange Microsoft OAuth authorization code for user profile and issue a session token. If the user does not exist, a new user is created. - [Validate Session](https://compass.docs.sunnyscoach.com/auth/validate-session.md): Protected route that returns the user object from the request body when the session is valid. Requires authentication and appropriate role middleware. - [Globe Component](https://compass.docs.sunnyscoach.com/components/globe.md): A 3D interactive globe visualization component built with Three.js and React Three Fiber - [Add Users to Department](https://compass.docs.sunnyscoach.com/departments/add-users.md): Admin-only endpoint to add multiple users to a department with a specific role. - [Assign Department Manager](https://compass.docs.sunnyscoach.com/departments/assign-manager.md): Admin-only endpoint to assign a user as the manager of a department. - [Delete Department](https://compass.docs.sunnyscoach.com/departments/delete.md): Admin-only endpoint to delete a department by its ID. Returns the deleted department’s basic details if successful. - [Get Department Hierarchy](https://compass.docs.sunnyscoach.com/departments/hierarchy.md): Admin-only endpoint that retrieves the full hierarchical structure of all departments. Each department may include nested child departments inside the `children` array. - [List Departments](https://compass.docs.sunnyscoach.com/departments/list.md): Admin-only endpoint to retrieve a list of departments. - If both `start` and `end` are `0`, all departments are returned. - Otherwise, returns departments between the given start and end indexes (zero-based). - [Create Department](https://compass.docs.sunnyscoach.com/departments/new.md): Admin-only endpoint to create a new department. - [Update Department](https://compass.docs.sunnyscoach.com/departments/update.md): Admin-only endpoint to update department details. - [Events & Venues Guide](https://compass.docs.sunnyscoach.com/docs/calendar/index.md): Comprehensive guide to managing events, venues, and logistics in Compass - [Detailed Agent Statistics](https://compass.docs.sunnyscoach.com/email-meter/stats/agents-detailed.md): Retrieves detailed statistics for each agent within the given date range. Includes counts, response time distributions (with and without delays), and resolution times. If `startDate` or `endDate` are not provided, the date range defaults to one week from today. - [Agent Performance Summary](https://compass.docs.sunnyscoach.com/email-meter/stats/agents-highlevel.md): Retrieves high-level metrics for agent performance and email assignment efficiency within the given date range. - Includes statistics on **time to assign agents** and **number of agents per conversation**. - If no `startDate` or `endDate` is provided, defaults to the last 7 days (a week from tod… - [Client Domain Email Trends](https://compass.docs.sunnyscoach.com/email-meter/stats/clients/incoming-trends.md): Returns the **daily incoming email trends** for the **top 5 client domains** within the specified date range. - Only incoming emails are counted. - If no date range is provided, the system automatically adjusts it to a **week from today**. - The response provides a `series` array suitable for t… - [Clients with Lowest Resolution Rates](https://compass.docs.sunnyscoach.com/email-meter/stats/clients/lowest-resolved.md): Returns the **top 3 client domains** that have the **highest number of unresolved conversations** within the given date range. - A conversation is considered **unresolved** if it does **not** contain a `resolved` category. - The system automatically adjusts the date range to **a week from today**… - [Client Domain Response Times](https://compass.docs.sunnyscoach.com/email-meter/stats/clients/response-times.md): Returns the **top 10 client domains** with the **longest median response times** over the specified date range. - Calculates response times from all email conversations. - Includes both **overall stats** and **per-domain median response times**. - If the date range is not provided, it defaults… - [Top Client Domains](https://compass.docs.sunnyscoach.com/email-meter/stats/clients/top-domains.md) - [Email Count Statistics](https://compass.docs.sunnyscoach.com/email-meter/stats/email-counts.md): Returns email conversation and thread statistics for a specified date range. - Counts total conversations, responded conversations, spam, and "no response required" messages. - Tracks incoming and sent email counts, average thread size, and number of unique email addresses involved. - [Daily Email Activity Trend](https://compass.docs.sunnyscoach.com/email-meter/stats/emails-trend.md): Retrieves the trend of incoming and sent emails across the specified date range. - If no `startDate` or `endDate` is provided, the system defaults to the last 7 days (a week from today). - Each label in `labels` corresponds to a date in the range, and `series` contains counts of sent and receive… - [Flagged Conversation Statistics](https://compass.docs.sunnyscoach.com/email-meter/stats/flags.md): Retrieves statistics related to flagged conversations, including the time to flag and the time to complete resolution after flagging. If `startDate` or `endDate` are not provided, defaults to the last 7 days. - [Hourly Email Traffic Trends](https://compass.docs.sunnyscoach.com/email-meter/stats/hourly-trends.md): Returns hourly email volume (received and sent) between the given start and end dates. Each day is broken down into 24 hourly buckets, showing how many emails were received and sent during each hour. - **If no date range is provided**, the system automatically adjusts it to a week from today. -… - [Conversation Resolution Times](https://compass.docs.sunnyscoach.com/email-meter/stats/resolved-times.md): Retrieves metrics about how long conversations take to resolve. - Includes resolution times from the **first received email** and from the **last assigned agent**, both with and without delays. - If no `startDate` or `endDate` is provided, defaults to the last 7 days (a week from today). - [Email Response Time Statistics](https://compass.docs.sunnyscoach.com/email-meter/stats/response-times.md): Returns detailed response time metrics for emails within the specified date range. - Includes both **first response** and **overall response** time statistics. - Also reports SLA(Service Level Agreement currently 15 mins) compliance breakdown (responses within SLA vs. after SLA). - If no/inval… - [Microsoft Graph Webhook](https://compass.docs.sunnyscoach.com/email-meter/webhook.md): Webhook endpoint used by Microsoft Graph for email notification events. - During subscription setup, Microsoft Graph sends a **validation token** as a query parameter, which must be echoed back. - For subsequent notifications, Microsoft Graph sends email event data in the request body. - This… - [HubSpot Integration](https://compass.docs.sunnyscoach.com/geocoding/hubspot-integration.md): Guide to integrating the Geocoding API with HubSpot for automated ticket processing - [Geocoding API](https://compass.docs.sunnyscoach.com/geocoding/index.md): Convert addresses and location names into geographic coordinates - [Export HubSpot Tickets](https://compass.docs.sunnyscoach.com/hubspot-tickets/export.md): Exports HubSpot tickets based on selected filters, columns, and department. The response returns a downloadable file (Excel, CSV, or JSON) depending on the requested format. - **Requires authentication** - If no format is specified, defaults to `xlsx`. - [List HubSpot Tickets](https://compass.docs.sunnyscoach.com/hubspot-tickets/list.md): Retrieves a list of HubSpot tickets within the specified date range and pagination window. Supports filtering by agent, feedback category, search keyword, and department code. **Notes:** - If the calculated `pageSize` (`endIndex - startIndex`) exceeds **50**, it is automatically resized to 50.… - [Get Ticket Filters](https://compass.docs.sunnyscoach.com/hubspot-tickets/list-filters.md): Retrieves possible filters and their values to be displayed in the frontend dropdowns. Currently supports two filter types: - **Agents** (all agents) - **Categories** (all feedback categories) - [Agents Statistics](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/agents.md): Retrieve incident, resolution, and SLA statistics grouped by agent for the specified date range. - [Compliments Count](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/compliments-count.md): Retrieve total tickets, total compliments, and compliment percentage for a specified date range. - [Departments Statistics](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/departments.md): Retrieve detailed incident statistics grouped by department for the specified date range. - [Feedback Severities](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/feedback-severities.md): Retrieve aggregated feedback severity statistics for the specified date range. - [Geo Map](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/geo-map.md): Retrieve GeoJSON data for rendering a heatmap on a world or regional map. - [Geo Map Filters](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/geo-map-filters.md): Retrieve available geographic filter options for map-based statistics. - [Incidents Trend](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/incident-trend.md): Retrieve the daily trend of incidents (tickets) within a specified date range. - [Resolution Times](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/resolution-times.md): Retrieve minimum, maximum, average, and median resolution times for incidents within a date range. - [Resolution Times SLA](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/resolution-times-sla.md): Retrieve SLA compliance statistics for incident resolution times within the specified date range. - [Top Affiliates Involved](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/top-affiliates-involved.md): Retrieve a list of top affiliates involved in incidents within a specified date range. - [Top Categories](https://compass.docs.sunnyscoach.com/hubspot-tickets/stats/top-categories.md): Retrieve the top categories for incidents within a specified date range. - [Get Ticket Details](https://compass.docs.sunnyscoach.com/hubspot-tickets/ticket-details.md): Retrieves the full details of a single HubSpot ticket using its unique `ticketId`. Requires authentication and a valid HubSpot ticket ID. The endpoint validates the ticket ID before fetching data and returns complete ticket metadata including content, related contacts, categories, and assigned age… - [API Reference](https://compass.docs.sunnyscoach.com/overview/api-reference.md): Complete reference for all COMPASS API endpoints organized by category and functionality. - [Authentication Guide](https://compass.docs.sunnyscoach.com/overview/authentication.md): Learn how to authenticate with the COMPASS API using OAuth 2.0 and JWT tokens. - [Introduction](https://compass.docs.sunnyscoach.com/overview/introduction.md): Welcome to the COMPASS API documentation. Learn about our RESTful API and how to integrate with our services. - [Quick Start Guide](https://compass.docs.sunnyscoach.com/overview/quick-start.md): Get up and running with COMPASS API in minutes. Learn the basics with practical examples. - [Troubleshooting Guide](https://compass.docs.sunnyscoach.com/overview/troubleshooting.md): Common issues and solutions when working with COMPASS API. Get help with authentication, errors, and integration problems. - [List System Permissions](https://compass.docs.sunnyscoach.com/permissions/list.md): Returns a list of all available system permissions. - [Attendance & Utilization Report](https://compass.docs.sunnyscoach.com/reports/attendance-utilization-report.md): Technical documentation for the Attendance & Utilization reporting system including configuration, calculations, and examples. - [Reporting Agent](https://compass.docs.sunnyscoach.com/reports/reporting-agent.md): Architecture and workflow of the COMPASS reporting agent system that processes reports and generates automated emails. - [Delete Transcription](https://compass.docs.sunnyscoach.com/transcription/delete.md): Permanently removes the transcription record for the specified audio file from the system. - [Get or Generate Transcription](https://compass.docs.sunnyscoach.com/transcription/get-transcription.md): Retrieves the transcription for a given file. If no transcription exists in the system, and a valid `audioUrl` is provided, a new transcription will be generated and stored. - [Add User Permissions](https://compass.docs.sunnyscoach.com/users/add-permissions.md): Adds one or more permissions to a user's existing permissions list. Only admin-level users can perform this action. - [Link User Accounts](https://compass.docs.sunnyscoach.com/users/link-accounts.md): Admin-only endpoint to link a secondary user account into a primary account. - The `userToLinkId` account will be deleted after merging its linked accounts into the primary `userId`. - [List Users](https://compass.docs.sunnyscoach.com/users/list.md): Admin-only endpoint to retrieve a list of users. - If both `start` and `end` are `0`, all users are returned. - Otherwise, returns users between the given start and end indexes (zero-based). - [Get Match Suggestions](https://compass.docs.sunnyscoach.com/users/match-suggestions.md): Admin-only endpoint that returns suggested user pairs that may represent the same person. Suggestions are generated by comparing emails and personal information (first name, last name, name). - [Get User Profile](https://compass.docs.sunnyscoach.com/users/profile.md): Endpoint to get the profile of the logged in user - [Remove User Permissions](https://compass.docs.sunnyscoach.com/users/remove-permissions.md): Removes one or more permissions from a user's existing permissions list. Only admin-level users can perform this action. - [Update User Department](https://compass.docs.sunnyscoach.com/users/update-department.md): Admin-only endpoint to set a user's department by department ID. - [Update Department Role](https://compass.docs.sunnyscoach.com/users/update-department-role.md): Admin-only endpoint to update a user's department role by user ID. - [Update Phone Number](https://compass.docs.sunnyscoach.com/users/update-phone.md): Admin-only endpoint to update the phone number stored in a user's personal information. - [Update RingCentral Extension](https://compass.docs.sunnyscoach.com/users/update-rcextension.md): Admin-only endpoint to update the Ring Central extension stored in a user's personal information. ## OpenAPI Specs - [openapi](https://compass.docs.sunnyscoach.com/openapi.yaml)