REST API Reference

Overview

The SOG Tracker REST API allows external systems to submit and retrieve performance metrics on behalf of a member company. It is designed for machine-to-machine integrations with accounting and field service platforms such as QuickBooks, ServiceTitan, and ConnectWise.

Authentication

Pass your API key as a Bearer token in every request:

Authorization: Bearer sog_yourprivatekeyhere
Content-Type: application/json

Rate Limits

When exceeded, returns HTTP 429 with a Retry-After header (seconds to wait).

Response Format

All responses are JSON. Errors include an error string.

// Success
{ "success": true, "message": "Metrics saved successfully.", "data": { ... } }

// Error
{ "error": "Month must be between 1 and 12." }

Endpoints

Health Check

curl -H "Authorization: Bearer sog_yourkey" https://sogtracker.com/api/v1/status

Submit Metrics

Required: month (1–12) and year. All other fields optional. KPIs are auto-calculated.

POST /api/v1/metrics
Authorization: Bearer sog_yourkey
Content-Type: application/json

{
  "month": 3,
  "year": 2025,
  "revenue": 187500,
  "cogs": 112000,
  "billable_hours": 1240,
  "gross_profit": 75500,
  "total_num_employees": 14
}

Update Metrics (Partial)

Only the fields you include are changed. All others retain existing values. Returns 404 if the month doesn't exist yet — use POST first.

PUT /api/v1/metrics/2025/3
Authorization: Bearer sog_yourkey
Content-Type: application/json

{ "revenue": 195000, "cogs": 115000 }

List All Months

Optional query params: limit (default 24, max 120) and offset (default 0).

GET /api/v1/metrics?limit=12&offset=0

Latest Month

GET /api/v1/metrics/latest

Get Specific Month

GET /api/v1/metrics/2025/3

Input Field Reference

All fields are numeric. Omit fields your system doesn't track — KPIs are only calculated when their required inputs are present.

Gross Profit Margin

Sales Efforts

Project Hours Variance

Labor Efficiency

Cash Management

Expense Management

Revenue Mix

Auto-Calculated KPIs

These are returned in calculated_kpis — you never submit them.

QuickBooks Integration

ServiceTitan Integration

ConnectWise Integration

Example Integration Script

// sog-tracker-submit.js
const API_KEY = process.env.SOG_API_KEY; // Never hardcode keys
const BASE_URL = 'https://sogtracker.com/api/v1';

async function submitMonthlyMetrics(month, year, data) {
  const response = await fetch(`${BASE_URL}/metrics`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ month, year, ...data })
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`SOG Tracker error: ${err.error}`);
  }

  const result = await response.json();
  console.log('KPIs:', result.data.calculated_kpis);
  return result;
}

submitMonthlyMetrics(3, 2025, {
  revenue: 187500, cogs: 112000, gross_profit: 75500,
  billable_hours: 1240, net_income: 22000,
  accounts_receivable: 94000, num_days_in_month: 31,
  month_ending_balance: 185000, month_beginning_balance: 172000,
  cash_liquid_assets: 210000, operating_expenses_em: 68000,
  current_month_op_expenses: 68000, previous_month_op_expenses: 65000,
  total_num_employees: 14, service_revenue: 52000,
  recurring_revenue: 38000, revenue_from_parts: 21000, revenue_from_labor: 76500,
});

Troubleshooting