Customer-Vibes Analytics API

API Reference Production Ready

Complete API reference for the Customer-Vibes Analytics API. Provides secure access to customer profile and vehicle data from the Customer Database through a high-performance API gateway. Built on a proven 3-step async pattern with intelligent caching for optimal performance.

🔒 Enterprise Security

System-level JWT authentication with predefined queries for maximum security

⚡ Real-time Processing

Daily data updates with 24-hour delta queries for incremental sync

Quick Start

cURL

# Submit analytics query
curl -X POST https://public-api.dev2.steercrm.dev/api/data/v1/analytics/customer-vibes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{}'

# Check status (replace with actual queryId)
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/{queryId}/status \
  -H "X-API-Key: YOUR_API_KEY"

# Get results
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/{queryId}/results?partition=0 \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

// Submit query and get results
async function fetchAnalytics() {
  // Step 1: Submit query
  const response = await fetch('/api/data/v1/analytics/customer-vibes', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'YOUR_API_KEY'
    },
    body: '{}'
  });
  const { queryId } = await response.json();

  // Step 2: Poll for completion
  let status;
  do {
    const statusResponse = await fetch(`/api/data/v1/analytics/${queryId}/status`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    ({ status } = await statusResponse.json());
    if (status === 'RUNNING') await new Promise(r => setTimeout(r, 1000));
  } while (status === 'RUNNING');

  // Step 3: Get results
  if (status === 'SUCCESS') {
    const resultsResponse = await fetch(`/api/data/v1/analytics/${queryId}/results?partition=0`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY' }
    });
    return await resultsResponse.json();
  }
}

Python

import requests
import time

def fetch_analytics():
    headers = {'X-API-Key': 'YOUR_API_KEY'}

    # Submit query
    response = requests.post('https://public-api.dev2.steercrm.dev/api/data/v1/analytics/customer-vibes',
                           json={}, headers=headers)
    query_id = response.json()['queryId']

    # Poll for completion
    while True:
        status_response = requests.get(f'https://public-api.dev2.steercrm.dev/api/data/v1/analytics/{query_id}/status',
                                     headers=headers)
        status = status_response.json()['status']

        if status == 'SUCCESS':
            break
        elif status == 'RUNNING':
            time.sleep(1)
        else:
            raise Exception(f'Query failed with status: {status}')

    # Get results
    results_response = requests.get(f'https://public-api.dev2.steercrm.dev/api/data/v1/analytics/{query_id}/results',
                                  params={'partition': 0}, headers=headers)
    return results_response.json()

Base Configuration

API Base URL

Development: https://public-api.dev2.steercrm.dev Production: https://api-prod.example.com

🔐 API Key Authentication

Authentication Method:

• Use the X-API-Key header for all API requests
• Example: X-API-Key: your-api-key-here

⚠️ Upcoming Authentication Changes

We are actively migrating to OAuth 2.0 standard authentication to provide enhanced security and improved integration capabilities for our vendor partners. This transition will occur in the coming months and will require updates to your integration.

What to Expect with OAuth 2.0: The new authentication system will implement industry-standard OAuth 2.0 flows, requiring:

• Client ID and Client Secret for application identification
• Access Tokens for API request authentication (short-lived for security)
• Refresh Tokens for seamless token renewal without user re-authentication

Action Required:

• Current Integrations: Continue using API Key authentication until further notice
• New Integrations: Consider planning for OAuth 2.0 implementation
• Stay Informed: We will provide at least 90 days advance notice before deprecating API Key authentication
• Migration Support: Comprehensive documentation and migration guides will be provided

Available Endpoints

Discovery Endpoint

Get information about all available predefined analytics queries.

Request

GET /api/data/v1/analytics/types

Response

{
    "availableQueries": [
        {
            "description": "Customer profiles for Vibes integration",
            "endpoint": "/api/data/v1/analytics/customer-vibes",
            "type": "customer-vibes"
        },
        {
            "description": "Customer profiles updated within last 24 hours",
            "endpoint": "/api/data/v1/analytics/customer-vibes-delta-24h",
            "type": "customer-vibes-delta-24h"
        }
    ],
    "message": "Only predefined queries are allowed for security"
}

Analytics Queries

Customer Analytics

Full Dataset Query Complete Data

Retrieve complete customer profiles and vehicle data for initial data loads or complete snapshots.

Request

POST /api/data/v1/analytics/customer-vibes
Content-Type: application/json

{}

Response

{
    "description": "Customer profiles for Vibes integration",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "customer-vibes",
    "status": "RUNNING",
    "success": true
}

Use Cases:

• Initial system setup and data population
• Complete data synchronization
• Data warehouse migrations
• Comprehensive reporting and analytics

24-Hour Delta Query Incremental

Retrieve only records updated within the last 24 hours for efficient incremental updates.

Request

POST /api/data/v1/analytics/customer-vibes-delta-24h
Content-Type: application/json

{}

Response

{
    "description": "Customer profiles updated within last 24 hours",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-96b3-0006-874e00e6407a/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-96b3-0006-874e00e6407a/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-96b3-0006-874e00e6407a",
    "queryType": "customer-vibes-delta-24h",
    "status": "RUNNING",
    "success": true
}

Empty Results Example

When no records have been updated in the last 24 hours:

{
  "success": true,
  "queryId": "01bf6563-0003-96b3-0006-874e00e6407a",
  "queryType": "customer-vibes-delta-24h",
  "partition": 0,
  "totalPartitions": 1,
  "rowCount": 0,
  "data": [],
  "metadata": {
    "format": "jsonv2",
    "numRows": 0,
    "partitionInfo": [
      {
        "rowCount": 0,
        "uncompressedSize": 0
      }
    ]
  }
}

Note

Empty Results: When no records have been updated in the last 24 hours, the response will contain an empty data array and rowCount: 0. This is normal behavior for incremental queries.

Use Cases:

• Regular synchronization processes (hourly/daily)
• Real-time data pipeline updates
• Change detection and event processing
• Efficient bandwidth usage for large datasets

Business360 Insights

Organizational Hierarchy

Retrieve the complete organizational structure showing relationships between brands, tenants, and shops.

Request

POST /api/data/v1/analytics/business360-hierarchy
Content-Type: application/json

{}

Response

{
    "description": "Business360 organizational hierarchy",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "business360-hierarchy",
    "status": "RUNNING",
    "success": true
}

Description: Returns complete organizational structure with brand, tenant, and shop relationships for navigation and filtering.

Brand-Level Insights

Retrieve aggregated KPIs and performance metrics at the brand level for executive dashboards.

Request

POST /api/data/v1/analytics/business360-insights-brand
Content-Type: application/json

{
  "brand_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Body Parameters:

• brand_id (required): Brand UUID for filtering insights

Response

{
    "description": "Brand-level aggregated insights",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "business360-insights-brand",
    "status": "RUNNING",
    "success": true
}

Description: Provides high-level executive insights with brand-level KPIs aggregated across all tenants and shops.

Tenant-Level Insights

Retrieve aggregated performance metrics at the tenant level for operational management.

Request

POST /api/data/v1/analytics/business360-insights-tenant
Content-Type: application/json

{
  "tenant_id": "f2e3d4c5-b6a7-8901-2345-6789abcdef01"
}

Body Parameters:

• tenant_id (required): Tenant UUID for filtering insights

Response

{
    "description": "Tenant-level aggregated insights",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "business360-insights-tenant",
    "status": "RUNNING",
    "success": true
}

Description: Operational management insights with performance metrics rolled up across all shops within a tenant.

Shop-Level Insights

Retrieve granular performance data at the shop location level for detailed analysis.

Request

POST /api/data/v1/analytics/business360-insights-shop
Content-Type: application/json

{
  "shop_id": "c3d4e5f6-a7b8-9012-3456-789abcdef012"
}

Body Parameters:

• shop_id (required): Shop UUID for filtering insights

Response

{
    "description": "Shop-level granular insights",
    "links": {
        "results": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results",
        "status": "/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status"
    },
    "message": "Query submitted successfully",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "business360-insights-shop",
    "status": "RUNNING",
    "success": true
}

Description: Detailed KPIs for individual shop locations with granular performance metrics.

Query Management

Status Monitoring

Monitor the execution progress of submitted queries with real-time status updates.

Request

GET /api/data/v1/analytics/{queryId}/status

Response

{
    "message": "Statement executed successfully.",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "customer-vibes",
    "resultSetMetaData": {
        "format": "jsonv2",
        "numRows": 25921,
        "partitionInfo": [
            {
                "compressedSize": 28566,
                "rowCount": 255,
                "uncompressedSize": 100216
            },
            {
                "compressedSize": 117829,
                "rowCount": 1071,
                "uncompressedSize": 417859
            }
            // ... variable number of partitions based on dataset size
        ],
        "rowType": [
            {
                "name": "STEER_CUSTOMER_ID",
                "type": "text",
                "nullable": true,
                "database": "DATAMART_DEV",
                "schema": "DWH_PRODUCT",
                "table": "DM_CUSTOMER"
            },
            {
                "name": "VAST_CUSTOMER_ID",
                "type": "text",
                "nullable": true,
                "database": "DATAMART_DEV",
                "schema": "DWH_PRODUCT",
                "table": "DM_INTEGRATION"
            },
            {
                "name": "CUSTOMER_TYPE",
                "type": "text",
                "nullable": true
            },
            {
                "name": "CUSTOMER_STAGE",
                "type": "text",
                "nullable": false
            }
            // ... complete schema with 28 fields total
        ]
    },
    "stats": {
        "createdOn": 1759231895424
    },
    "status": "SUCCESS",
    "submittedAt": "2025-09-30T11:31:35.717Z"
}

Tip

Partition Usage: Large datasets are automatically partitioned. Use the partitionInfo array to determine how many partitions are available, then iterate through them using ?partition=0, ?partition=1, etc. Each partition contains a subset of the total rows.

Status Values

RUNNING

Query is currently executing on the database

SUCCESS

Query completed successfully, results are available

FAILED

Query execution failed, check error details

Results Retrieval

Retrieve the processed data from completed queries with support for large dataset partitioning.

Request

GET /api/data/v1/analytics/{queryId}/results?partition=0

Parameters:

• partition (optional): Partition number (0-based). Default: 0

Note

For large datasets, the database automatically creates partitions when needed. Check the partitionInfo field in the status response to see all available partitions.

Response

{
  "success": true,
  "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
  "queryType": "customer-vibes",
  "partition": 0,
  "totalPartitions": 24, // varies by dataset size
  "rowCount": 255,
  "data": [
    [
      "4b62d36a-a5d6-4308-8d40-af6358104775",
      "0015069558",
      "Person",
      "Customer",
      "John",
      "Smith",
      null,
      "Houston",
      "Texas",
      "77001",
      null,
      null,
      "Eligible",
      "john.smith@example.com",
      "Eligible",
      "f154d8db-cbe1-461e-bc7b-5fae9eeeead2",
      "15000171790",
      "Chevrolet",
      "2020",
      "Impala",
      "CHEVROLET",
      "IMPALA",
      "2020",
      "Downtown Service Center",
      "Premier Auto Services",
      "1701457200.000000000",
      null,
      "1750254263.614000000"
    ]
    // ... additional records as arrays
  ]
}

Note

Response Format: The data field contains an array of arrays (not objects). Each inner array represents one customer record with field values in the exact same order as the rowType schema array returned from the /status endpoint. The field order and structure match the resultSetMetaData.rowType property from the status response.

Postman Collection

Test the API quickly and efficiently with our pre-configured Postman collection. Get started in minutes with ready-to-use requests and environment configurations.

📦 Complete Collection

Pre-configured requests for all API endpoints including:

• Customer analytics queries (full dataset & 24h delta)
• Status monitoring and result retrieval
• Health checks
• Built-in variable management and error handling

🔧 Environment Setup

Development Environment

Ready-to-use environment configuration with:

• Dev2 API URL (https://public-api.dev2.steercrm.dev)
• API key variable placeholder
• Automatic query ID persistence
• Response validation scripts

Download & Setup

Quick Start

Get testing in 3 steps:

1. Download the collection and environment files
2. Import both files into Postman
3. Set your API key in the environment variables

📦 Download Collection

🌐 Download Environment

Detailed Setup

Step-by-step setup instructions:

1. Download Files

   • Collection: Contains all API requests and test scripts
   • Environment: Contains URL and API key configuration

2. Import into Postman

   • Open Postman → File → Import
   • Select both downloaded JSON files
   • Choose “API Gateway - Dev2 SteerCRM” environment

3. Configure API Key

   • Click the environment dropdown (top right)
   • Edit “API Gateway - Dev2 SteerCRM” environment
   • Set the api_key variable to your actual API key
   • Save the environment

4. Test the Integration

   • Run “Health & Metrics → Gateway Health” first
   • Execute the customer query workflow in sequence:
     1. Submit Customer Query
     2. Check Query Status
     3. Get Results - Partition 0

Note

Note: The collection automatically stores query IDs between requests, so you can run the workflow seamlessly without manual copying.

Collection Features

Advanced features included:

🔄 Automated Workflows

• Query ID persistence across requests
• Response validation and error handling
• Performance timing and metrics

🎯 Smart Testing

• Pre-request validation scripts
• Detailed console logging for debugging

📊 Environment Management

• Separate variables for different environments
• Secure API key handling (marked as secret)
• URL configuration for easy environment switching

Data Schema Reference

For comprehensive data model specifications including field definitions, business rules, consent management, and integration considerations, please refer to the dedicated Data Model documentation.

Performance & Caching

Performance Metrics

⚡ Database Processing

Variable timing Initial query execution depends on data size and complexity

🚀 Cached Results

Redis Caching Cached results for identical queries delivered instantly

⏱️ Result Cache TTL

1 hour Results cached for optimal performance

🔄 Status Cache TTL

5 minutes Running query status cached briefly

Rate Limiting

Caution

Rate Limits in Effect

• Throttle: 10 requests per second (burst: 15)
• Daily Quota: 200 requests per day

Plan your query submission accordingly for optimal performance.

Large Dataset Handling

For large datasets, the database automatically creates partitions when needed. The number of partitions varies based on dataset size and complexity.

📊 Partition Strategy

Automatic Partitioning

• Large result sets are automatically divided into manageable partitions
• Number of partitions varies based on dataset size and data characteristics
• Partition size varies based on data characteristics and compression

Data Freshness & Updates

📊 Full Dataset

Complete Records All available customer and vehicle records from source systems

⏰ 24-Hour Delta

Recent Updates Records updated within the last 24 hours (based on Unix timestamp comparison)

🔄 Update Frequency

Daily Updates Source system updates processed once every 24 hours

🌐 Global Sync

Multi-tenant Supports multiple tenant environments and regions

---