Integration Management

The Integration Management submodule handles third-party service integration status monitoring, configuration management, and integration validation across multiple external platforms and services.

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/accounts/integrations	Get account integrations status
GET	/v1/accounts/usage	Get account resource usage
GET	/v1/accounts/balance	Get account balance

MongoDB Collections Used

Integration Token Collections

• bing-ads-tokens - Bing Ads API integration tokens
• google-analytics-tokens - Google Analytics API tokens
• google-ads-tokens - Google Ads API integration tokens
• google-business-tokens - Google Business Profile tokens
• facebook-ads-keys - Facebook Ads API integration keys
• callrail-keys - CallRail API integration keys
• calltrackingmetrics-keys - CallTrackingMetrics API keys
• tik-tok-tokens - TikTok Ads API integration tokens
• stripe-keys - Stripe payment integration keys
• square-up-tokens - Square payment integration tokens

Configuration Collections

• google-ads-configs - Google Ads account configurations
• analytics-googleanalytics-userconfigs - Google Analytics user configurations
• analytics-callrail-userconfigs - CallRail analytics configurations
• analytics-facebook-ads-userconfigs - Facebook Ads analytics configurations
• analytics-calltrackingmetrics-userconfigs - CallTrackingMetrics configurations
• analytics-tiktokanalytics-userconfigs - TikTok analytics configurations
• semrush-auths - SEMrush API authentication records

Supporting Collections

• _store.subscriptions - Active subscriptions for integration eligibility
• _accounts - Account records with integration status and settings

Integration Status Monitoring

Integration Health Check Flow

graph TD
    A[Integration Status Request] --> B[Load Account Tokens]
    B --> C[Validate Token Status]
    C --> D[Check Configuration]
    D --> E[Verify Subscription Eligibility]
    E --> F[Test API Connectivity]
    F --> G[Compile Status Report]
    G --> H[Return Integration Status]

Service Configuration Validation

graph TD
    A[Service Token Check] --> B{Token Exists?}
    B -->|Yes| C[Validate Configuration]
    B -->|No| D[Mark as Disconnected]
    C --> E{Config Complete?}
    E -->|Yes| F[Mark as Connected]
    E -->|No| G[Mark as Partially Configured]
    F --> H[Include Service Details]
    G --> H
    D --> H

Service Methods & Functionality

Core Integration Services

integrations() - Integration status retrieval

• Retrieves comprehensive integration status for accounts across all supported platforms
• Validates integration tokens and configuration completeness
• Supports both global and configured integration filtering modes
• Checks active subscriptions for integration eligibility and access
• Includes detailed integration configuration and connection status
• Provides service-specific settings like account IDs, property IDs, and configuration details
• Returns structured integration data with connection status and metadata

Supported Integration Platforms

Advertising Platforms

• Google Ads: Campaign management and analytics integration

  • Token validation and account configuration
  • Client and manager account relationships
  • ROI rate configuration and tracking

• Facebook Ads: Social media advertising integration

  • Meta Ads API integration with account validation
  • Ad account ID configuration and management
  • Campaign performance tracking integration

• Bing Ads: Microsoft advertising platform integration

  • Bing Ads API token validation
  • Account configuration and campaign management
  • Performance tracking and analytics integration

• TikTok Ads: Social media advertising integration

  • TikTok Ads API integration and token management
  • Advertiser ID configuration and validation
  • Campaign performance monitoring integration

Analytics Platforms

• Google Analytics: Website analytics integration

  • GA4 and Universal Analytics support
  • Property and view ID configuration
  • Analytics version management (v4 support)

• SEMrush: SEO and competitive analysis integration

  • Domain-based SEO tracking and analysis
  • Subscription-based access validation
  • Comprehensive SEO metrics integration

Call Tracking Services

• CallRail: Call tracking and analytics integration

  • Account and company ID configuration
  • Call tracking number management
  • Analytics integration and reporting

• CallTrackingMetrics: Advanced call tracking integration

  • Account and sub-account configuration
  • Call analytics and performance tracking
  • Integration with reporting systems

Payment Processing

• Stripe: Payment processing integration

  • Connected account management and validation
  • Live mode and test mode configuration
  • Connected apps and integration status

• SquareUp: Point-of-sale payment integration

  • OAuth token validation and refresh
  • Payment processing configuration
  • Transaction tracking integration

Business Management

• Google Business: Business profile management

  • Google Business Profile API integration
  • Location management and updates
  • Review and rating monitoring

• Listings Management: Business listing services

  • Yext integration for business listings
  • Entity configuration and management
  • Subscription-based listing management

Resource Management Services

usage() - Account resource usage tracking

• Retrieves account resource usage and credit information with verification
• Integrates with credit verification systems for usage validation
• Provides detailed resource consumption metrics and limits
• Supports resource-specific usage tracking and monitoring
• Returns comprehensive usage data with credit balance information

balance() - Account balance management

• Provides account balance and currency information from Stripe integration
• Retrieves real-time balance data from payment processing systems
• Supports multiple currency formats and conversion tracking
• Integrates with payment processing for accurate balance reporting
• Returns current balance with currency and payment method information

Technical Implementation Details

Integration Architecture

• Token Management: Secure storage and validation of API tokens across platforms
• Configuration Validation: Comprehensive validation of service-specific configurations
• Subscription Checking: Integration eligibility validation based on active subscriptions
• Status Aggregation: Real-time compilation of integration status across services

Security & Authentication

• Token Security: Secure token storage and validation with expiration handling
• API Key Management: Encrypted storage of API keys and authentication credentials
• Access Control: Role-based access to integration configuration and management
• Permission Validation: Service-specific permission validation and scope checking

Performance & Reliability

• Caching Strategy: Efficient caching of integration status and configuration data
• Error Handling: Comprehensive error handling for API failures and timeouts
• Retry Logic: Intelligent retry mechanisms for temporary service failures
• Status Monitoring: Real-time monitoring of integration health and connectivity

Business Logic Implementation

Integration Status Compilation

1. Token Retrieval: Load integration tokens for the specified account
2. Configuration Validation: Validate service-specific configuration completeness
3. Subscription Checking: Verify active subscriptions for integration eligibility
4. API Connectivity: Test API connectivity and token validity
5. Status Aggregation: Compile comprehensive integration status report
6. Metadata Inclusion: Include service-specific configuration and settings
7. Response Formatting: Format structured response with connection details

Service Configuration Management

1. Token Validation: Validate API tokens and authentication credentials
2. Configuration Completeness: Check for required configuration parameters
3. Account Relationships: Validate service account relationships and permissions
4. Subscription Eligibility: Verify subscription requirements for service access
5. Feature Availability: Check feature availability based on subscription tiers
6. Status Determination: Determine final integration status and capabilities

Key Features

Comprehensive Integration Coverage

• Multiple Platforms: Support for 10+ major advertising, analytics, and business platforms
• Real-time Status: Live integration status monitoring and validation
• Configuration Management: Complete configuration validation and management
• Subscription Integration: Automatic subscription-based feature availability

Advanced Status Monitoring

• Token Validation: Comprehensive API token validation and health checking
• Configuration Completeness: Detailed validation of service-specific configurations
• Connectivity Testing: Real-time API connectivity and service availability testing
• Status Aggregation: Unified status reporting across all integrated services

Security & Reliability

• Token Security: Encrypted storage and secure handling of API credentials
• Permission Management: Role-based access control for integration management
• Error Handling: Robust error handling and recovery mechanisms
• Performance Optimization: Efficient caching and performance optimization strategies

Business Intelligence

• Usage Tracking: Comprehensive resource usage monitoring and credit tracking
• Balance Management: Real-time account balance and payment status monitoring
• Subscription Validation: Automatic feature availability based on subscription status
• Integration Analytics: Detailed analytics on integration usage and performance