Muse API Documentation

Overview

Version 2.3.1 • Last Updated: May 25, 2025 • Production Ready

The Compass API provides comprehensive tools for automated tax deduction discovery, transaction categorization and tax planning insights. It is built for fintech applications, accounting software and tax preparation services.

🚀 Key Features

  • Automated transaction categorization with ML-powered confidence scoring
  • Real time deduction discovery and optimization
  • Seamless Plaid integration for bank connectivity
  • Historical tax return analysis with amendment opportunities
  • Comprehensive tax insights and strategic planning

Getting Started

Request Partner Credentials

To access the Compass API, you'll need to request partner credentials by emailing us at tech@musetax.com.

    Required Credentials:

  • Client ID
  • Client Secret
  • SSL Certificate (.crt file)

Rate Limiting

Rate limits are applied per client to ensure fair usage and optimal performance for all users.

Endpoint Category Rate Limit Window
Authentication 10 requests 1 minute
Transaction Processing 100 requests 1 minute
Deduction Analysis 50 requests 1 minute
OCR Document Processing 20 requests 1 minute

Rate Limit Headers

All API responses include rate limit information in the headers: 


  X-RateLimit-Limit: 100
  X-RateLimit-Remaining: 95
  X-RateLimit-Reset: 1635724800
Tip: Monitor the X-RateLimit-Remaining header to avoid hitting rate limits. Implement exponential backoff when you receive a 429 status code.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure. All error responses follow a consistent format.

Standard Error Response


{
  "error": 
  {
    "code": "INVALID_REQUEST",
    "message": "The request is missing required parameters",
    "details": 
        {
          "missing_fields": ["user_id"]
        }
  }
}

Common Error Codes

Code HTTP Status Description
200 Success The request was successful
201 Created The resource was successfully created
400 Bad Request Request parameters are invalid
401 Unauthorized Invalid or expired API key
403 Forbidden API key lacks required permissions
404 Not Found Requested resource doesn't exist
429 Rate Limited Too many requests
500 Internal Server Error Internal processing error

Authentication & Authorization

Before calling any API endpoints, you must authenticate your application to ensure secure communication. Muse uses JWT (JSON Web Token) for authentication.

  • Obtain API Credentials: Request your client_id and client_secret by contacting tech@musetax.com.
  • Generate an Access Token: Use your credentials to call the /auth/token endpoint and retrieve a time limited access token.

Get Your Access Token

Use this endpoint to retrieve the access token required in the Authorization header for all API requests.

POST /v2/api/auth/token
Security Note: Keep your API keys secure and never expose them in client-side code. Use environment variables in production.

Refresh Your Access Token

Refresh your access token using the old refresh token.

POST /v2/api/auth/refresh-token

Compass API

User Management

Manage users securely using authenticated API requests. This includes creating, updating, retrieving, and deleting user records, all protected through JWT and certificate-based authentication.

Create User

Register a new user in the Compass system for transaction analysis.

POST /v2/api/user
Important: Save the returned user_id in your system for all future API calls.

Get User

Retrieve user information by user ID.

GET /v2/api/user/:user_id

Update User

Update a user's email or username using their user ID.

PATCH /v2/api/user/:user_id

Get Taxpayer Profile

Retrieve detailed tax profile information for a specific user including income, deductions, dependents, expenses, and other tax-related data.

GET /v2/api/taxpayer-profile/:user_id
Note: This endpoint uses both internal data and external sources (e.g., Plaid) to build a complete taxpayer profile.

Plaid Integration

Create Link Token

Use this endpoint to generate a link token, which is required to initialize the Plaid Link interface. This token securely connects your application to a user’s financial institution.

The generated token should be passed to the client to launch the Plaid Link flow. It is short lived and must be used shortly after creation.

Ensure you create a new link token for each user session where the Plaid Link is initialized.

POST /v2/api/create_link_token

Exchange Public Token

This endpoint exchanges a public token generated by the Plaid Link for a permanent access token. The access token is used to make authenticated requests to the Plaid API on behalf of the user.

The public token is short lived and can only be used once. After this exchange, securely store the access token to access user data (e.g., accounts, transactions).

POST /v2/api/exchange_public_token

Transaction Processing

Process and analyze financial transactions securely using authenticated API requests. This includes retrieving categorized transactions, calculating deductions and filtering by date or user.

Fetch User Transactions

Import and retrieve user transactions from Plaid to begin categorization and analysis.

POST /v2/transactions/fetch

Add User Transactions

Manually add or batch-import user transactions for analysis, bypassing Plaid sync.

POST /v2/api/transactions
Performance Advisory: The API supports processing up to 10,000 transactions in a single request or response. For optimal performance and to avoid timeouts or memory issues, it is recommended to paginate or batch large datasets accordingly.

Get Categorized Transactions

Retrieve transactions organized by tax-relevant categories with deduction analysis.

GET /v2/api/transactions/categorize/:user_id

Investment Analysis

Analyze user investments to gain insights into portfolio performance, risk exposure, and asset allocation. Use authenticated API requests to securely access and evaluate investment data.

Fetch Investment Transactions

Import and process investment transactions for tax analysis.

POST /investments/fetch

Add Investment Transactions

Import and process investment transactions for tax analysis.

POST /v2/api/investments
Performance Advisory: The API supports processing up to 10,000 transactions in a single request or response. For optimal performance and to avoid timeouts or memory issues, it is recommended to paginate or batch large datasets accordingly.

Get Categorized Investment Transactions

Returns categorized investment transactions that have been processed and analyzed for tax relevance.

GET /v2/api/investments/categorize/:user_id

Transaction Processing And Customization

Customize and refine how investment transactions are classified. This section allows you to inspect details, override categorizations, and create exportable summaries for reporting purposes.

Get Transaction Details

Retrieve detailed information for specific transactions.

POST /v2/api/transactions/details

Update Transaction Category

Modify the category assignment for specific transactions.

PATCH /v2/api/transactions/category

Export Transactions

This endpoint allows exporting a user's transaction history as a downloadable CSV file. It is useful for generating financial reports, audit documentation, or user-facing summaries.

Trigger this endpoint to provide users with a professional, printable document of their past transactions.

GET /v2/api/export/transactions/:user_id

Custom Categorization Rules

Create business-specific categorization rules to improve accuracy for your unique transactions.

POST /v2/api/rules/custom
Pro Tip: Custom rules take precedence over default categorization logic and can significantly improve accuracy for business-specific vendors.

Tax Optimization

Identify tax-saving opportunities by analyzing user transactions and investment data. The APIs help calculate potential deductions, categorize expenses, and optimize financial decisions for better tax outcomes.

Get Potential Deductions

Retrieve intelligent deduction recommendations based on transaction analysis.

GET /v2/api/deductions/potential

Get Tax Insights

Receive personalized financial insights and tax optimization recommendations.

GET /v2/api/insights/{user_id}

Muse Score

Generates a comprehensive muse score based on the user's profile, filing history, income patterns and deduction behavior. This score helps users understand their tax performance and areas for potential optimization.

POST /v2/api/muse-score

OCR Document Processing

This endpoint enables the upload and processing of scanned tax documents using OCR (Optical Character Recognition). It supports various form types such as 1040, W-2, 1099, etc. and helps in extracting structured tax-related data.

The uploaded document is automatically classified and parsed into relevant tax fields, enabling faster and more accurate tax preparation.

Analyze Prior Year Form 1040

This endpoint retrieves tax related transaction summaries for a given account and tax year. It provides information such as total income, deductions and other financial data relevant for tax reporting and analysis.

Use this data to assist users in understanding their taxable income, planning for returns, or generating tax summaries for submission.

POST /v2/api/tax-returns

Get Tax Return Summary

Retrieve detailed tax-related transaction summaries for a specific tax return document using its ID. This data includes total income, deductions, taxable income, tax paid, expected refunds, and all associated categorized transactions for the given tax year.

Use this endpoint to provide users with detailed insights into their tax filing and support activities such as audit readiness, reporting, or refund estimation.

GET /v2/api/tax-return/details/:document_id

Analyze Form W-2

Upload a Form W-2 (PDF or image) for income verification and tax reporting of wage income.

POST /v2/api/upload-w2
Note: Only PDF, PNG and JPEG formats are supported. Maximum file size: 10MB.

Get Schedule C Data API

Retrieve IRS Form 1040, Schedule C data for business owners including income, expense and deduction details.

GET /v2/api/export/schedule-c

Webhook

Receive real-time notifications about user financial activities such as transactions, investments and account changes. Webhooks enable instant updates, improved automation and integration with your systems.

Plaid Transaction Updates

Configure webhook endpoints to receive real-time transaction updates from Plaid.

Description:

By integrating this webhook with your Plaid account, you enable an automated and efficient method for tracking financial transactions. Once configured, our system will automatically:

  • Fetch new transaction data from Plaid.
  • Categorize transactions for comprehensive deduction analysis.
  • Provide proactive alerts to users regarding potential or dedicated deductions.


This eliminates the need for repeated manual transaction tracking, streamlining the process of financial insights and user notifications.

Configuration:

To utilize this feature, configure this endpoint as a webhook in your Plaid developer dashboard.

Webhook URL Configuration:

POST {Baseurl}/v2/api/plaid-webhook

Compass Widgets

Compass UI Widgets provide turnkey, embeddable components that deliver complete tax optimization functionality with minimal integration effort. These widgets integrate with our API ecosystem through secure server-side authentication while providing rich, interactive user experiences.

Secure Architecture - All sensitive credentials remain on your server. Widgets use secure session tokens for frontend operations.

Compass Widget Session Token

This endpoint generates a secure session token used to initialize a Compass widget on the frontend.

POST /v2/api/compass-widget-session

Widget Session Token

This endpoint generates a secure session token used to initialize a widget on the frontend.

POST /v2/api/widgets/session

Security & Authentication Model

All API requests require authentication using JWT with certificate-based security.

Server-Side Authentication Required

Widgets never expose sensitive credentials in frontend code. All authentication happens server-side through your backend systems.

Secure Token Exchange

Transaction Review Widget Screenshot

Session Token Architecture

  • Short-lived tokens (2-hour expiration) for frontend widget operations
  • No sensitive credentials are ever exposed in browser
  • Automatic token refresh handled by widgets
  • Secure HTTPS communication for all data exchange

Integration Prerequisites & Flow

Step 1: User Creation (Server-Side)

Before using any widgets, create a Compass user account through your backend. 


            // Your Backend - Create Compass User
            const createCompassUser = async (userEmail, plaidUserId) => {
              const authResponse = await fetch('{BaseUrl}/v2/api/auth/token', {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                  'X-Client-Certificate': process.env.COMPASS_CERT
                },
                body: JSON.stringify({
                  client_id: process.env.COMPASS_CLIENT_ID,
                  client_secret: process.env.COMPASS_CLIENT_SECRET
                })
              });
            
              const { access_token } = await authResponse.json();
            
              const userResponse = await fetch('{BaseUrl}/v2/api/user', {
                method: 'POST',
                headers: {
                  'Authorization': `Bearer ${access_token}`,
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                  username: userEmail.split('@')[0],
                  email: userEmail,
                  plaid_user_id: plaidUserId
                })
              });
            
              const { user_id } = await userResponse.json();
              await saveCompassUserId(userEmail, user_id);
              return user_id;
            };

Step 2: Transaction Data Sync (Server-Side)

Sync user's financial data before widgets can provide insights.


// Your Backend - Sync Transaction Data
const syncUserTransactions = async (compassUserId, plaidAccessToken, plaidAccountId) => {
const authResponse = await fetch('/v2/api/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Certificate': process.env.COMPASS_CERT
  },
  body: JSON.stringify({
    client_id: process.env.COMPASS_CLIENT_ID,
    client_secret: process.env.COMPASS_CLIENT_SECRET
  })
});

const { access_token } = await authResponse.json();

const syncResponse = await fetch('{BaseUrl}/v2/transactions/fetch', {
  method: 'POST',
  headers: {
    'Authorization': \`Bearer \${access_token}\`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plaid_access_token: plaidAccessToken,
    account_id: plaidAccountId
   
  })
});

return await syncResponse.json();
};

Step 3: Widget Session Token Generation (Server-Side)

Generate secure session tokens for frontend widget initialization. 


// Your Backend - Generate Widget Session Token
app.post('/v2/api/compass-widget-session', async (req, res) => {
const { user_id } = req.body; // Your internal user ID

// Get stored Compass user ID
const compassUserId = await getCompassUserId(user_id);

// Authenticate with Compass
const authResponse = await fetch('/v2/api/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Certificate': process.env.COMPASS_CERT
  },
  body: JSON.stringify({
    client_id: process.env.COMPASS_CLIENT_ID,
    client_secret: process.env.COMPASS_CLIENT_SECRET
  })
});

const { access_token } = await authResponse.json();

// Generate widget session token
const sessionResponse = await fetch('{BaseUrl}/v2/api/widgets/session', {
  method: 'POST',
  headers: {
    'Authorization': \`Bearer \${access_token}\`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user_id: compassUserId,
   })
});

const { widget_session_token } = await sessionResponse.json();

res.json({ 
  sessionToken: widget_session_token,
  compassUserId: compassUserId
});
});

Step 4: Frontend Widget Initialization

Use secure session tokens to initialize widgets.


// Your Frontend - Secure Widget Initialization
const initializeCompassWidgets = async () => {
// Get secure session token from your backend
const response = await fetch('/v2/api/compass-widget-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: currentUser.id })
});

const { sessionToken, compassUserId } = await response.json();

// Initialize widgets with secure session token
CompassWidgets.TransactionReview.init({
  containerId: 'compass-transaction-review',
  sessionToken: sessionToken, // Secure token from your backend
  user_id: compassUserId,
  autoHeight: true
});
};

Transaction Review Widget

Streamlines the transaction categorization process after initial data sync. Provides an intuitive interface for users to review AI-generated categories and approve deductions.

  • User created via /v2/user API
  • Transactions synced via /v2/transactions/fetch
  • Session token generated from your backend

Core Functionality

  • Secure Data Loading: Uses session token to call /transactions/categorized
  • Smart Categorization Display: Shows AI-based categories with confidence levels
  • Transaction Category Change: Allows users to update the category of any transaction using the /transactions/category API.
HTML Integration (No Sensitive Data Exposed)

<div id="compass-transaction-review"></div>
<script src="{BaseUrl}/v2/transaction-review.js"></script>
<script>
fetch('/v2/api/compass-widget-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: currentUser.id })
})
.then(response => response.json())
.then(({ sessionToken, compassUserId }) => {
  CompassWidgets.TransactionReview.init({
    containerId: 'compass-transaction-review',
    sessionToken,
    user_id: compassUserId,
    autoHeight: true,
    onReviewComplete: function(categorizedCount, potentialSavings) {
      console.log(`${categorizedCount} transactions reviewed, $${potentialSavings} in potential savings`);
    }
  });
});
</script>
React Component Integration

  import { TransactionReviewWidget } from 'COMPASS-SDK';  //Text : You will get installation detail along with your account credentails.. This text will be added wherever there's react code.
  import { useState, useEffect } from 'react';

  const SecureTransactionReview = ({ user_id }) => {
  const [sessionData, setSessionData] = useState(null);

  useEffect(() => {
    fetch('/v2/api/compass-widget-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ user_id })
    })
    .then(response => response.json())
    .then(setSessionData);
  }, [user_id]);

  if (!sessionData) return <div>Loading...</div>;

  return (
    <TransactionReviewWidget
      sessionToken={sessionData.sessionToken}
      user_id={sessionData.compassUserId}
      autoHeight={true}
      theme="light"
      onReviewComplete={(categorizedCount, potentialSavings) => {
        // Handle completion
      }}
    />
  );
  };

Configuration Options

Customize the Transaction Review Widget behavior and appearance using the following configuration options:

Property Type Default Description
sessionToken string required Secure session token from your backend
user_id string required user ID
autoHeight boolean true Widget automatically adjusts height
theme string 'light' Visual theme ('light', 'dark', 'auto')
showConfidenceScores boolean true Display categorization confidence levels
bulkActionsEnabled boolean true Enable bulk categorization features

API Integration Flow

The following steps outline how the Transaction Review Widget securely interacts with the Compass backend:

  1. Session Validation: Widget validates the provided session token before performing any operations.
  2. Data Fetch: Automatically calls /transactions/categorized to load user transactions.
  3. User Interaction: Users review, approve, or edit AI-generated transaction categories.
  4. Category Updates: Each category change triggers a /transactions/category API call.
  5. Savings Recalculation: Deduction calculations are updated in real-time via /deductions/potential.

Transaction Review Widget

Transaction Review Widget Screenshot Transaction Review Widget Screenshot
  • Secure interface with no exposed credentials
  • Transactions grouped by AI-suggested categories
  • Confidence indicators and bulk selection options
  • Real-time savings counter and progress tracking

Tax Insights Dashboard Widget

Deliver personalized tax optimization recommendations using securely processed financial data and AI-powered insights.

Prerequisites

  • User created and transaction data synced
  • Widget session token generated from your backend
  • Recent transaction categorization completed

Core Functionality

  • Secure Insights Loading: Uses session token to call /insights/{user_id} API
  • Priority Recommendations: Highlights top 3 most impactful opportunities
  • Actionable Interface: Includes direct links to implement recommendations
  • Real-Time Updates: Automatically refreshes as categorized transaction data changes

Secure Integration

Embed the widget using the code snippet below. No sensitive data is exposed on the frontend. 

<!-- Secure Dashboard Integration -->
<div id="compass-insights-dashboard"></div>
<script src="{BaseUrl}/v2/insights-dashboard.js"></script>
<script>
// Initialize with secure session token
initializeCompassSession()
  .then(({ sessionToken, compassUserId }) => {
    CompassWidgets.InsightsDashboard.init({
      containerId: 'compass-insights-dashboard',
      sessionToken: sessionToken,
      user_id: compassUserId,
      layout: 'comprehensive',
      onInsightAction: function(insightType, actionData) {
        // Route to appropriate features in your platform
        handleInsightAction(insightType, actionData);
      }
    });
  });
</script>
React Component Integration

  import { useEffect } from 'react';
  
  const CompassInsightsDashboard = () => {
    useEffect(() => {
      const loadScriptAndInit = async () => {
        // Load external widget script
        const script = document.createElement('script');
        script.src = '{BaseUrl}/v2/insights-dashboard.js';
        script.async = true;
  
        script.onload = async () => {
          // Get secure session from your backend
          const res = await fetch('/v2/api/compass-widget-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ user_id: 'compass_user_67890' })
          });
  
          const { sessionToken, compassUserId } = await res.json();
  
          // Initialize the Compass Insights Dashboard
          if (window.CompassWidgets?.InsightsDashboard) {
            window.CompassWidgets.InsightsDashboard.init({
              containerId: 'compass-insights-dashboard',
              sessionToken,
              user_id: compassUserId,
              layout: 'comprehensive',
              onInsightAction: (insightType, actionData) => {
                handleInsightAction(insightType, actionData);
              }
            });
          }
        };
  
        document.body.appendChild(script);
      };
  
      loadScriptAndInit();
  
      return () => {
        // Cleanup script on unmount
        const existingScript = document.querySelector(
          'script[src="{BaseUrl}/v2/insights-dashboard.js"]'
        );
        if (existingScript) {
          document.body.removeChild(existingScript);
        }
      };
    }, []);
  
    const handleInsightAction = (insightType, actionData) => {
      console.log('Insight action triggered:', insightType, actionData);
      // Implement your custom action logic here
    };
  
    return <div id="compass-insights-dashboard" />;
  };
  
  export default CompassInsightsDashboard;

Configuration Options

Property Type Default Description
sessionToken string required Secure session token from your backend
user_id string required user ID
layout string 'comprehensive' Dashboard layout option
showTopInsights number 3 Number of priority insights to highlight
autoRefresh number 300000 Auto-refresh interval in milliseconds (default: 5 minutes)

API Integration Flow

  • Secure Authentication: Validates session token
  • Insights Generation: Calls /insights/{user_id} for personalized recommendations
  • Priority Analysis: Identifies top 3 most valuable opportunities
  • Interactive Display: Presents actionable recommendations
  • Real-Time Monitoring: Updates insights as data changes

Tax Insights Dashboard Widget

Transaction Review Widget Screenshot

  • Priority insights with clear dollar amounts
  • Actionable recommendations with implementation buttons
  • Real-time savings projections and progress indicators

Deduction Discovery Widget

Purpose

Systematically identifies and organizes potential tax deductions using securely processed transaction data.

Prerequisites

  • Complete transaction sync and categorization
  • Widget session token with deduction permissions
  • User profile data for personalized analysis

Core Functionality

  • Secure Deduction Analysis: Uses session token to call /deductions/potential API
  • Schedule-Based Organization: Groups by IRS tax schedules
  • Supporting Evidence: Links to transactions via /transactions/details API
  • Interactive Selection: Real-time savings calculation

Secure Integration


<!-- Secure Deduction Discovery -->
<div id="compass-deduction-discovery"></div>
<script src="{BaseUrl}/v2/deduction-discovery.js"></script>
<script>
initializeCompassSession()
  .then(({ sessionToken, compassUserId }) => {
    CompassWidgets.DeductionDiscovery.init({
      containerId: 'compass-deduction-discovery',
      sessionToken: sessionToken,
      user_id: compassUserId,
      showSavingsCalculator: true,
      groupBySchedule: true,
      onDeductionSelect: function(deductionData) {
        // Handle deduction selections
        updateTaxCalculations(deductionData);
      }
    });
  });
</script>
React Component Integration

  import { useEffect } from 'react';
  
  const CompassDeductionDiscovery = () => {
    useEffect(() => {
      const loadScriptAndInit = async () => {
        const script = document.createElement('script');
        script.src = '{BaseUrl}/v2/deduction-discovery.js';
        script.async = true;
  
        script.onload = async () => {
          const res = await fetch('/v2/api/compass-widget-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ user_id: 'compass_user_67890 })
          });
  
          const { sessionToken, compassUserId } = await res.json();
  
          if (window.CompassWidgets?.DeductionDiscovery) {
            window.CompassWidgets.DeductionDiscovery.init({
              containerId: 'compass-deduction-discovery',
              sessionToken,
              user_id: compassUserId,
              showSavingsCalculator: true,
              groupBySchedule: true,
              onDeductionSelect: (deductionData) => {
                handleDeductionSelect(deductionData);
              }
            });
          }
        };
  
        document.body.appendChild(script);
      };
  
      loadScriptAndInit();
  
      return () => {
        const existingScript = document.querySelector(
          'script[src="{BaseUrl}/v2/deduction-discovery.js"]'
        );
        if (existingScript) {
          document.body.removeChild(existingScript);
        }
      };
    }, []);
  
    const handleDeductionSelect = (deductionData) => {
      console.log('Selected deduction:', deductionData);
      // updateTaxCalculations(deductionData);
    };
  
    return <div id="compass-deduction-discovery" />;
  };
  
  export default CompassDeductionDiscovery;

API Integration Flow

  • Session Authentication: Validates secure session token
  • Deduction Analysis: Calls /deductions/potential for comprehensive analysis
  • Schedule Organization: Groups deductions by IRS tax schedules
  • Supporting Data: Fetches transaction details via /transactions/details
  • Interactive Modeling: Real-time savings calculations

Deduction Discovery Widget

Transaction Review Widget Screenshot

  • Schedule-organized deductions with confidence levels
  • Interactive selection with real-time savings updates
  • Supporting transaction evidence and professional layout

OCR Document Processing Widget

Purpose

Analyzes previously filed tax returns against current data to identify missed opportunities.

Prerequisites

  • Current year transaction data fully processed
  • Widget session token with analysis permissions
  • User consent for document upload and processing

Core Functionality

  • Secure File Processing: Handles /analysis/1040 API integration
  • Comparative Analysis: Compares filed vs. potential deductions
  • Amendment Guidance: ROI analysis for filing amended returns
  • Professional Referral: Integration for complex cases

Secure Integration

API Integration Flow

  1. Secure Upload:
    User uploads their IRS Form 1040 via a secure, encrypted widget interface.
  2. Document Processing:
    Widget sends the file to /analysis/1040 API for secure extraction and parsing of return data.
  3. Comparative Analysis:
    Extracted return data is automatically compared with current financial data from /deductions/potential API.
  4. Gap Identification:
    AI-powered logic detects any missed or underclaimed deductions based on IRS guidelines and current transactions.
  5. Amendment Recommendations:
    System presents actionable next steps, including potential refund amount and guidance on filing amended returns (Form 1040-X).

OCR Document Processing Widget

Transaction Review Widget Screenshot Transaction Review Widget Screenshot Transaction Review Widget Screenshot

  • Secure file upload interface for IRS Form 1040
  • Side-by-side comparison of claimed vs. missed deductions
  • Amendment recommendations with ROI calculation

Implementation Security Best Practices

Backend Requirements

  • Environment Variables: Store all Compass credentials as environment variables
  • Certificate Management: Secure storage of client certificates
  • Token Expiration: Implement token refresh mechanisms
  • Audit Logging: Log all API interactions for security monitoring

Frontend Security

  • No Credential Exposure: Never include client secrets in frontend code
  • Session Token Only: Widgets only receive short-lived session tokens
  • HTTPS Required: All widget communications use secure HTTPS
  • Content Security Policy: Configure CSP headers for widget domains

Data Protection

  • Encryption in Transit: All data encrypted during transmission
  • Temporary Storage: Session tokens automatically expire
  • User Consent: Clear consent flows for data processing

Complete Integration Example

Backend Setup


// Environment Configuration
process.env.COMPASS_CLIENT_ID = 'your_client_id';
process.env.COMPASS_CLIENT_SECRET = 'your_client_secret';
process.env.COMPASS_CERT = 'path_to_certificate.crt';

// User Onboarding Flow
app.post('/api/user/onboard-tax', async (req, res) => {
const { user_id, plaidAccessToken, plaidAccountId } = req.body;

try {
  // Step 1: Create Compass user
  const compassUserId = await createCompassUser(
    req.user.email, 
    req.user.plaidUserId
  );

  // Step 2: Sync transaction data
  await syncUserTransactions(
    compassUserId, 
    plaidAccessToken, 
    plaidAccountId
  );

  // Step 3: Generate widget session
  const sessionToken = await generateWidgetSession(compassUserId);

  res.json({
    success: true,
    sessionToken: sessionToken,
    compassUserId: compassUserId
  });
} catch (error) {
  res.status(500).json({ error: 'Onboarding failed' });
}
});

Frontend Implementation


// Complete Secure Widget Initialization
const initializeTaxOptimization = async (user_id) => {
try {
  // Get secure session from backend
  const response = await fetch('/v2/api/compass-widget-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ user_id })
  });

  const { sessionToken, compassUserId } = await response.json();

  // Initialize all widgets securely
  CompassWidgets.TransactionReview.init({
    containerId: 'transaction-review',
    sessionToken: sessionToken,
    user_id: compassUserId
  });

  CompassWidgets.InsightsDashboard.init({
    containerId: 'insights-dashboard',
    sessionToken: sessionToken,
    user_id: compassUserId
  });

  CompassWidgets.DeductionDiscovery.init({
    containerId: 'deduction-discovery',
    sessionToken: sessionToken,
    user_id: compassUserId
  });

} catch (error) {
  console.error('Widget initialization failed:', error);
}
};

This secure architecture ensures that sensitive credentials never appear in frontend code while providing seamless widget functionality through proper API integration flow.

CheckBoost API

Tax Calculation

The Tax Calculation Service is designed to simplify the complex process of calculating tax withholdings, specifically for the W-4 form. By leveraging up-to-date IRS rules and tax regulations, this service ensures that tax calculations are performed accurately and efficiently. It takes into account a variety of personal financial factors, such as income, age, dependents, and filing status, to determine the appropriate withholding amount.This enables employees to make informed decisions about their withholding strategy.

Perform Tax Calculation

The Perform Tax Calculation endpoint executes a comprehensive tax withholding analysis based on submitted employee financial data. This endpoint processes the information to determine optimal W-4 withholding settings that align with the employee's financial goals.

When invoked, the endpoint analyzes the employee's current withholding status against their projected tax liability, calculating the difference between current and optimal withholding amounts. It evaluates multiple factor.

POST /v2/api/tax/calculate-w4-tax

Generate W-4 Form

The Ask My Uncle Sam™ service generates personalized W-4 forms based on users' financial circumstances. After creating a tax profile through the Register New User endpoint, users provide their income details, filing status, and dependent information to the Fetch W-4 Form endpoint. The service then returns a properly completed W-4 form with all fields populated according to their specific situation.

Users can update their information as life changes occur (marriage, children, etc.), and the service will recalculate the appropriate W-4 values in real-time. For optimal implementation, an intuitive frontend should collect the required information, process it through the API, and display the completed form for immediate preview and use.

Register New User

This endpoint allows users to create their tax profile by submitting personal information including name, address, and contact details. After successful registration, users receive a unique identifier that connects all their future tax calculations and form interactions in one secure account.

POST /v2/api/user/create

Fetch W-4 Form

This endpoint generates a personalized W-4 withholding form based on the financial information provided. It accommodates both complete and partial information submissions, allowing users to progressively build their W-4 as they gather relevant financial details or update specific sections as their circumstances change.

POST /v2/api/user/summary

Education Mode

The Ask My Uncle Sam™ service features an Education Mode with an AI-powered chat assistant nicknamed Ask My Uncle Sam . This Tax Estimate Chatbot allows users to ask real-world tax questions in natural language and receive accurate, jargon-free responses. The chatbot helps users understand complex tax concepts, withholding strategies, and the implications of various life changes on their tax situation, all without requiring specialized tax knowledge.

Tax Estimate Chatbot

Muse includes a built-in, AI-powered chat assistant nicknamed “Ask My Uncle Sam™” Employees can ask real-world tax questions in natural language and receive accurate, jargon-free responses.

  • Example questions include:
  • How many allowances should I claim?
  • Will I owe if I switch from single to married?
  • What’s the difference between pre-tax and post-tax deductions?
POST /v2/api/message

Support & Resources

Get help when you need it with our comprehensive support resources and developer community.

📚 Documentation

Comprehensive guides and tutorials

documentation.musetax.com

📧 API Support

Direct support for technical issues

tech@musetax.com

Response Times

Priority Level Response Time Description
Critical 2 hours Production outages or security issues
High 4 hours Significant functionality issues
Standard 24 hours General questions and minor issues
Enhancement 2 weeks Feature requests and improvements