Getting Started

Welcome! This guide will help you integrate the Steer-Vibes Analytics API into your application quickly and efficiently.

Authentication & Credentials

🔐 API Key Authentication

API Key Format:

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

API Key Security:

• Store API keys securely (environment variables, secret managers)
• Never commit API keys to version control or logs
• Use different API keys for development, staging, and production environments

⚠️ 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

Understanding the API

The Steer Analytics API follows a 3-step async pattern optimized for large dataset processing. This pattern is based on the Snowflake SQL API standard:

1️⃣ Submit

Submit Query Send your analytics request and receive a unique query ID for tracking

2️⃣ Monitor

Check Status Poll the status endpoint until query execution completes. The response includes partition metadata.

3️⃣ Retrieve

Get Results (Partitioned) Fetch each partition separately using the results endpoint with ?partition=N

💡 Why Partitions?

Large datasets are automatically split into partitions for efficient transfer. When a query completes, the status response tells you how many partitions exist. You must fetch each partition individually to retrieve the complete dataset.

Your First API Call

Note

Token Management: Replace YOUR_API_KEY in all examples below with your actual API key. API keys should be rotated regularly and stored securely using environment variables or secret management systems.

Let’s make your first API call to retrieve Steer customer analytics.

Step 1: Submit Query

# Submit a query for complete customer data
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 '{}'

Expected Response:

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

Note

Save the Query ID: You’ll need the queryId for the next steps. In this example, it’s 01bf6563-0003-9701-0006-874e00e6507e.

Step 2: Check Status

# Check query status (replace {queryId} with actual ID)
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/status \
  -H "X-API-Key: YOUR_API_KEY"

While Running:

{
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "status": "RUNNING",
    "message": "Query is executing..."
}

When Complete (with Partition Metadata):

{
    "message": "Statement executed successfully.",
    "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
    "queryType": "customer-vibes",
    "status": "SUCCESS",
    "resultSetMetaData": {
        "numRows": 25921,
        "partitionInfo": [
            {
                "compressedSize": 28566,
                "rowCount": 255,
                "uncompressedSize": 100216
            },
            {
                "compressedSize": 117829,
                "rowCount": 1071,
                "uncompressedSize": 417859
            }
            // ... more partitions based on data size
        ]
    }
}

🔑 Key Information: Partition Metadata

The partitionInfo array tells you how results are split:

• Array length = total number of partitions to fetch
• rowCount = number of records in each partition
• Index position = partition number (0-based)

In this example, there are multiple partitions. You must fetch each partition separately in Step 3.

Note

Status Polling: Keep checking the status until it changes from RUNNING to SUCCESS or FAILED. Recommended polling interval: 1-2 seconds.

Step 3: Get Results

Results are split into partitions that must be fetched individually. Use the ?partition=N query parameter (0-indexed) to retrieve each partition.

Fetch the first partition (partition=0):

# Get partition 0 (first partition)
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results?partition=0 \
  -H "X-API-Key: YOUR_API_KEY"

Response for partition 0:

{
  "success": true,
  "queryId": "01bf6563-0003-9701-0006-874e00e6507e",
  "queryType": "customer-vibes",
  "partition": 0,
  "totalPartitions": 24,
  "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",
      "Toyota",
      "2020",
      "Camry",
      "TOYOTA",
      "CAMRY",
      "2020",
      "Downtown Service Center",
      "Premier Auto Services",
      "1701457200.000000000",
      null,
      "1750254263.614000000"
    ]
    // ... more customer records (255 total in this partition)
  ]
}

Fetch remaining partitions:

# Get partition 1
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results?partition=1 \
  -H "X-API-Key: YOUR_API_KEY"

# Get partition 2
curl https://public-api.dev2.steercrm.dev/api/data/v1/analytics/01bf6563-0003-9701-0006-874e00e6507e/results?partition=2 \
  -H "X-API-Key: YOUR_API_KEY"

# Continue until partition = totalPartitions - 1

⚠️ Important: Fetch ALL Partitions

To retrieve the complete dataset, you must:

1. Check totalPartitions in any results response (or count partitionInfo array from status)
2. Loop through partitions from 0 to totalPartitions - 1
3. Combine the data arrays from all partitions

Missing partitions = incomplete data!

Note

Data Format: The data field contains an array of arrays (not objects). Each inner array represents one customer record with field values in the same order as the schema columns.

Query Types Explained

The API offers multiple query types for different use cases:

Customer Analytics Queries

Complete Dataset

Endpoint: /api/data/v1/analytics/customer-vibes

When to Use:

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

Expected Volume:

• All customer and vehicle records
• Typical response: 10,000+ records
• Processing time: Variable (depends on data size)
• Cached response: Instant

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 '{}'

24-Hour Delta

Endpoint: /api/data/v1/analytics/customer-vibes-delta-24h

When to Use:

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

Expected Volume:

• Only records updated in last 24 hours
• Typical response: 100-1,000 records
• Cached response: Instant

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

Business360 Insights Queries

Hierarchy

Endpoint: /api/data/v1/analytics/business360-hierarchy

Description: Returns complete organizational structure showing the relationships between brands, tenants, and shops.

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

Brand Insights

Endpoint: /api/data/v1/analytics/business360-insights-brand

Description: Aggregated KPIs and performance metrics at the brand level, providing high-level executive insights across all tenants and shops.

curl -X POST https://public-api.dev2.steercrm.dev/api/data/v1/analytics/business360-insights-brand \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"brand_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Tenant Insights

Endpoint: /api/data/v1/analytics/business360-insights-tenant

Description: Aggregated performance metrics at the tenant level, rolling up all shops within a tenant for operational management insights.

curl -X POST https://public-api.dev2.steercrm.dev/api/data/v1/analytics/business360-insights-tenant \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"tenant_id": "f2e3d4c5-b6a7-8901-2345-6789abcdef01"}'

Shop Insights

Endpoint: /api/data/v1/analytics/business360-insights-shop

Description: Granular performance data at the shop location level, providing detailed KPIs for individual locations.

curl -X POST https://public-api.dev2.steercrm.dev/api/data/v1/analytics/business360-insights-shop \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"shop_id": "c3d4e5f6-a7b8-9012-3456-789abcdef012"}'

Performance Tips

🚀 Use Caching

Results are cached for 1 hour. Identical queries will return instantly with cached data.

⏱️ Choose the Right Query

Use delta queries for regular sync operations to minimize data transfer and processing time.

📊 Handle Partitions

Large datasets are automatically partitioned. Always iterate through all partitions to get complete data.

🔄 Implement Retry Logic

Add exponential backoff for failed requests and handle transient network issues.

Rate Limits & Best Practices

Caution

Rate Limits

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

Design your application to respect these limits to ensure optimal performance.

Best Practices

1. Batch Operations: Group multiple data needs into single query cycles
2. Cache Locally: Store results locally to minimize API calls
3. Use Delta Queries: For regular sync operations, use 24-hour delta queries
4. Handle Errors Gracefully: Implement proper error handling and retry logic
5. Monitor Performance: Track query completion times and optimize accordingly