Quick Start Guide

Get started with COMPASS API in just a few minutes. This guide will walk you through the essential steps to make your first API calls and understand the core concepts.

Prerequisites

OAuth Provider: Google or Microsoft account
HTTP Client: Postman, curl, or any programming language
Base URL: http://localhost:2000

Step 1: Get Your Authentication Token

Option A: Using Google OAuth

Get Authorization Code
- Navigate to Google OAuth consent screen
- Receive authorization code after user consent

Exchange for JWT Token

curl -X POST 'http://localhost:2000/auth/signin-google/YOUR_AUTH_CODE' \
  -H 'Content-Type: application/json'

Option B: Using Microsoft OAuth

Get Authorization Code
- Navigate to Microsoft OAuth consent screen
- Receive authorization code after user consent

Exchange for JWT Token

curl -X POST 'http://localhost:2000/auth/signin-microsoft/YOUR_AUTH_CODE' \
  -H 'Content-Type: application/json'

Response:

{
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "64b7f1a2e4b0a5d3f9c12345",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "department": "OPS"
    }
  }
}

Step 2: Make Your First API Call

Use the token from Step 1 to access protected endpoints:

curl -X GET 'http://localhost:2000/users/profile' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Response:

{
  "message": "",
  "data": {
    "id": "64b7f1a2e4b0a5d3f9c12345",
    "email": "user@example.com",
    "name": "John Doe",
    "profilePicture": "https://lh3.googleusercontent.com/...",
    "role": "user",
    "department": "OPS",
    "rcExtension": "101",
    "phone": "+1-555-123-4567",
    "permissions": ["users.view", "tickets.view"]
  }
}

Step 3: Explore Core Features

Get Available Permissions

curl -X GET 'http://localhost:2000/permissions/list' \
  -H 'Authorization: Bearer YOUR_TOKEN'

List Departments

curl -X GET 'http://localhost:2000/departments/list' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Get Email Statistics

curl -X GET 'http://localhost:2000/email-meter/stats/email-counts/2025-10-01/2025-10-20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Step 4: Try Advanced Features

Create a New Department

curl -X POST 'http://localhost:2000/departments/new' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Support",
    "code": "CS",
    "description": "Handles customer inquiries and support"
  }'

Get HubSpot Ticket Filters

curl -X GET 'http://localhost:2000/hubspot/tickets/list/filters' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Generate Audio Transcription

curl -X POST 'http://localhost:2000/transcription/get-transcription/FILE_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "audioUrl": "https://example.com/audio-file.mp3"
  }'

Code Examples

JavaScript/Node.js

const axios = require('axios');

class CompassAPI {
  constructor(baseURL = 'http://localhost:2000') {
    this.baseURL = baseURL;
    this.token = null;
  }

  async authenticate(provider, authCode) {
    try {
      const response = await axios.post(
        `${this.baseURL}/auth/signin-${provider}/${authCode}`
      );
      
      this.token = response.data.data.token;
      this.user = response.data.data.user;
      
      // Set default authorization header
      axios.defaults.headers.common['Authorization'] = `Bearer ${this.token}`;
      
      return response.data.data;
    } catch (error) {
      console.error('Authentication failed:', error.response?.data);
      throw error;
    }
  }

  async getUserProfile() {
    const response = await axios.get(`${this.baseURL}/users/profile`);
    return response.data.data;
  }

  async getDepartments() {
    const response = await axios.get(`${this.baseURL}/departments/list`);
    return response.data.data;
  }

  async getEmailStats(startDate, endDate) {
    const response = await axios.get(
      `${this.baseURL}/email-meter/stats/email-counts/${startDate}/${endDate}`
    );
    return response.data.data;
  }
}

// Usage
async function quickStart() {
  const api = new CompassAPI();
  
  // Authenticate
  await api.authenticate('google', 'YOUR_AUTH_CODE');
  console.log('Authenticated as:', api.user.name);
  
  // Get user profile
  const profile = await api.getUserProfile();
  console.log('User profile:', profile);
  
  // Get departments
  const departments = await api.getDepartments();
  console.log('Available departments:', departments);
  
  // Get email statistics
  const emailStats = await api.getEmailStats('2025-10-01', '2025-10-20');
  console.log('Email statistics:', emailStats);
}

quickStart().catch(console.error);

Python

import requests
import json

class CompassAPI:
    def __init__(self, base_url='http://localhost:2000'):
        self.base_url = base_url
        self.token = None
        self.headers = {'Content-Type': 'application/json'}
    
    def authenticate(self, provider, auth_code):
        """Authenticate with OAuth provider"""
        url = f'{self.base_url}/auth/signin-{provider}/{auth_code}'
        
        try:
            response = requests.post(url, headers=self.headers)
            response.raise_for_status()
            
            data = response.json()
            self.token = data['data']['token']
            self.headers['Authorization'] = f'Bearer {self.token}'
            
            return data['data']
        except requests.exceptions.RequestException as e:
            print(f'Authentication failed: {e}')
            raise
    
    def get_user_profile(self):
        """Get current user profile"""
        url = f'{self.base_url}/users/profile'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()['data']
    
    def get_departments(self):
        """List all departments"""
        url = f'{self.base_url}/departments/list'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()['data']
    
    def get_email_stats(self, start_date, end_date):
        """Get email statistics"""
        url = f'{self.base_url}/email-meter/stats/email-counts/{start_date}/{end_date}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()['data']

# Usage
def quick_start():
    api = CompassAPI()
    
    # Authenticate
    auth_data = api.authenticate('google', 'YOUR_AUTH_CODE')
    print(f"Authenticated as: {auth_data['user']['name']}")
    
    # Get user profile
    profile = api.get_user_profile()
    print(f"User: {profile['name']}, Department: {profile['department']}")
    
    # Get departments
    departments = api.get_departments()
    print(f"Found {len(departments)} departments")
    
    # Get email statistics
    email_stats = api.get_email_stats('2025-10-01', '2025-10-20')
    print(f"Total conversations: {email_stats['conversations']['total']}")

if __name__ == '__main__':
    quick_start()

React Component

import React, { useState, useEffect } from 'react';

function CompassDashboard() {
  const [user, setUser] = useState(null);
  const [departments, setDepartments] = useState([]);
  const [emailStats, setEmailStats] = useState(null);
  const [loading, setLoading] = useState(true);
  const [token, setToken] = useState(localStorage.getItem('token'));

  useEffect(() => {
    if (token) {
      loadDashboard();
    }
  }, [token]);

  const loadDashboard = async () => {
    try {
      // Get user profile
      const profileResponse = await fetch('/users/profile', {
        headers: { 'Authorization': `Bearer ${token}` }
      });
      const profileData = await profileResponse.json();
      setUser(profileData.data);

      // Get departments
      const deptResponse = await fetch('/departments/list', {
        headers: { 'Authorization': `Bearer ${token}` }
      });
      const deptData = await deptResponse.json();
      setDepartments(deptData.data);

      // Get email statistics
      const statsResponse = await fetch('/email-meter/stats/email-counts/2025-10-01/2025-10-20', {
        headers: { 'Authorization': `Bearer ${token}` }
      });
      const statsData = await statsResponse.json();
      setEmailStats(statsData.data);

    } catch (error) {
      console.error('Failed to load dashboard:', error);
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading dashboard...</div>;

  return (
    <div className="dashboard">
      <h1>Welcome, {user?.name}!</h1>
      
      <div className="user-info">
        <p><strong>Email:</strong> {user?.email}</p>
        <p><strong>Department:</strong> {user?.department}</p>
        <p><strong>Role:</strong> {user?.role}</p>
      </div>

      <div className="departments">
        <h2>Departments ({departments.length})</h2>
        <ul>
          {departments.map(dept => (
            <li key={dept.id}>{dept.name} ({dept.code})</li>
          ))}
        </ul>
      </div>

      {emailStats && (
        <div className="email-stats">
          <h2>Email Statistics</h2>
          <p><strong>Total Conversations:</strong> {emailStats.conversations.total}</p>
          <p><strong>Responded:</strong> {emailStats.conversations.responded}</p>
          <p><strong>Average Response Time:</strong> {emailStats.responseTimes.average} minutes</p>
        </div>
      )}
    </div>
  );
}

export default CompassDashboard;

Common Use Cases

1. User Management Dashboard

async function loadUserDashboard() {
  const api = new CompassAPI();
  await api.authenticate('google', authCode);
  
  const [users, departments, permissions] = await Promise.all([
    api.getUsers(),
    api.getDepartments(),
    api.getPermissions()
  ]);
  
  return { users, departments, permissions };
}

2. Email Analytics Report

async function generateEmailReport(startDate, endDate) {
  const api = new CompassAPI();
  await api.authenticate('google', authCode);
  
  const [emailCounts, responseTimes, agentStats] = await Promise.all([
    api.getEmailCounts(startDate, endDate),
    api.getResponseTimes(startDate, endDate),
    api.getAgentStats(startDate, endDate)
  ]);
  
  return {
    summary: emailCounts,
    performance: responseTimes,
    agents: agentStats
  };
}

3. Ticket Management System

async function loadTicketSystem() {
  const api = new CompassAPI();
  await api.authenticate('google', authCode);
  
  // Get available filters
  const filters = await api.getTicketFilters();
  
  // Get recent tickets
  const tickets = await api.getTickets('2025-10-01', '2025-10-20', 0, 50);
  
  return { filters, tickets };
}

Testing Your Integration

Using Postman

Import Collection
- Create new collection
- Set base URL: http://localhost:2000
- Add authorization variable: {{token}}
Authentication Request
- Method: POST
- URL: /auth/signin-google/{{authCode}}
- Save token to collection variables
Test Request
- Method: GET
- URL: /users/profile
- Headers: Authorization: Bearer {{token}}

Using curl Script

#!/bin/bash

# Configuration
BASE_URL="http://localhost:2000"
AUTH_CODE="YOUR_AUTH_CODE"

# Authenticate
echo "Authenticating..."
AUTH_RESPONSE=$(curl -s -X POST "${BASE_URL}/auth/signin-google/${AUTH_CODE}" \
  -H "Content-Type: application/json")

TOKEN=$(echo $AUTH_RESPONSE | jq -r '.data.token')

if [ "$TOKEN" = "null" ]; then
  echo "Authentication failed"
  exit 1
fi

echo "Authentication successful!"

# Test API calls
echo "Getting user profile..."
curl -s -X GET "${BASE_URL}/users/profile" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

echo "Getting departments..."
curl -s -X GET "${BASE_URL}/departments/list" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

echo "Getting email statistics..."
curl -s -X GET "${BASE_URL}/email-meter/stats/email-counts/2025-10-01/2025-10-20" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

Next Steps

Now that you’ve completed the quick start:

Explore Full Documentation - Dive into detailed API references
Build Your Application - Start integrating COMPASS features
Check Permissions - Understand access control system
Review Best Practices - Learn security and performance tips

Need Help?

Documentation: Browse our comprehensive guides
Examples: Check out our code samples
Support: Contact our development team
Community: Join our developer forums

Ready to build something amazing? Start exploring our complete API reference!

Getting Started

Reports

Quick Start Guide

Quick Start Guide

Prerequisites

Step 1: Get Your Authentication Token

Option A: Using Google OAuth

Option B: Using Microsoft OAuth

Step 2: Make Your First API Call

Step 3: Explore Core Features

Get Available Permissions

List Departments

Get Email Statistics

Step 4: Try Advanced Features

Create a New Department

Get HubSpot Ticket Filters

Generate Audio Transcription

Code Examples

JavaScript/Node.js

Python

React Component

Common Use Cases

1. User Management Dashboard

2. Email Analytics Report

3. Ticket Management System

Testing Your Integration

Using Postman

Using curl Script

Next Steps

Recommended Reading

Need Help?

Getting Started

Reports

Documentation Index

​Quick Start Guide

​Prerequisites

​Step 1: Get Your Authentication Token

​Option A: Using Google OAuth

​Option B: Using Microsoft OAuth

​Step 2: Make Your First API Call

​Step 3: Explore Core Features

​Get Available Permissions

​List Departments

​Get Email Statistics

​Step 4: Try Advanced Features

​Create a New Department

​Get HubSpot Ticket Filters

​Generate Audio Transcription

​Code Examples

​JavaScript/Node.js

​Python

​React Component

​Common Use Cases

​1. User Management Dashboard

​2. Email Analytics Report

​3. Ticket Management System

​Testing Your Integration

​Using Postman

​Using curl Script

​Next Steps

​Recommended Reading

​Need Help?

Quick Start Guide

Prerequisites

Step 1: Get Your Authentication Token

Option A: Using Google OAuth

Option B: Using Microsoft OAuth

Step 2: Make Your First API Call

Step 3: Explore Core Features

Get Available Permissions

List Departments

Get Email Statistics

Step 4: Try Advanced Features

Create a New Department

Get HubSpot Ticket Filters

Generate Audio Transcription

Code Examples

JavaScript/Node.js

Python

React Component

Common Use Cases

1. User Management Dashboard

2. Email Analytics Report

3. Ticket Management System

Testing Your Integration

Using Postman

Using curl Script

Next Steps

Recommended Reading

Need Help?