Campaign Analytics

Understand your Campaign Analytics

The Campaign Analytics API provides comprehensive performance metrics and insights for partner-driven campaigns through detailed analytics tracking and conversion metrics for your marketing initiatives.

What is the Campaign Analytics?

The Campaign Analytics API is like having a comprehensive campaign command center for your marketing efforts. It gives you deep insights into how specific campaigns perform across different time periods, tracking everything from insider engagement to conversion rates and revenue generation at the campaign level.

Why is Campaign Analytics useful?

Campaign analytics bridges individual campaign data with business outcomes, helping you optimize marketing strategies and budget allocation through data-driven campaign insights.

Marketing Teams: Track campaign ROI and optimize budget allocation based on real-time performance metrics and conversion data across all campaigns.
Finance Teams: Monitor revenue attribution at the campaign level and calculate true campaign ROI with detailed cost-benefit analysis.
Strategy Teams: Identify top-performing campaign patterns and replicate successful strategies across different time periods and audience segments.

The API works continuously in the background, capturing every campaign interaction and linking them to purchases, insider engagement, and revenue outcomes.

How does it work?

The API provides comprehensive campaign-level insights by aggregating all instances and interactions related to specific campaigns. You can track everything from basic engagement metrics to detailed conversion funnels and revenue attribution for individual campaigns.

What It Tracks: Campaign-specific instances, conversion rates, revenue attribution, insider engagement patterns, and performance trends across all time periods.
Example: See that Campaign A generated 234 instances with 70 purchases (29.9% conversion rate) and $5,397 total revenue across multiple insider segments this week.
Access Patterns: Time-based aggregation for trend analysis, purchase filtering for conversion optimization, and detailed instance tracking for performance evaluation.

Team	Benefit	Example
Marketing	Campaign optimization	"Campaign A achieves 29.9% conversion rate - scale this approach for similar products"
Finance	ROI tracking	"Track $5,397 revenue attributed specifically to Campaign A with detailed cost analysis"
Strategy	Performance insights	"Daily campaigns outperform weekly ones by 45% in conversion rates"

Authentication

All Campaign Analytics API requests require authentication using your secret key in the Authorization header.

Header Format

Authorization: Bearer sk_live_abc123def456...
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Authentication Requirements

All API requests require a valid secret key
Single key system (no public/private key separation)
Keys follow format: sk_live_ or sk_test_ + 32 character string
Keys are partner-specific and provide access only to that partner's campaign data

Standard Response Format

Success Response Template

{
  "success": "boolean",
  "message": "string",
  "data": "object",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Error Response Template

{
  "success": false,
  "error": "string",
  "message": "string",
  "fields": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Error Responses

All endpoints can return the following HTTP status codes and error responses:

Authentication & Authorization Errors

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing secret key",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

403 Forbidden

{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient permissions to access this campaign.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Client Errors

400 Bad Request

{
  "success": false,
  "error": "Bad Request",
  "message": "Validation failed for N fields",
  "fields": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

404 Not Found

{
  "success": false,
  "error": "Not Found",
  "message": "Campaign not found with the specified campaign_id",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

409 Conflict

{
  "success": false,
  "error": "Conflict",
  "message": "Request conflicts with current campaign state.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

422 Unprocessable Entity

{
  "success": false,
  "error": "Validation Error",
  "message": "Request validation failed.",
  "details": "string",
  "validation_errors": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

429 Too Many Requests

{
  "success": false,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Server Errors

500 Internal Server Error

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

502 Bad Gateway

{
  "success": false,
  "error": "Bad Gateway",
  "message": "Upstream service unavailable.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

503 Service Unavailable

{
  "success": false,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry later.",
  "details": "string",
  "retry_after": "number (seconds)",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

504 Gateway Timeout

{
  "success": false,
  "error": "Gateway Timeout",
  "message": "Request timeout. Please try again.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

API Endpoints

Campaign Analytics

Get Campaign Analytics

GET /api/partner/v1/campaigns/{campaign_id}/analytics
GET /api/partner/v1/campaigns/{campaign_id}/analytics?time_frame=per_day&limit=20&is_purchase=true

Retrieve aggregated campaign performance metrics and analytics data with comprehensive insights into campaign effectiveness, insider engagement, and conversion tracking across specified time periods.

Parameters:

time_frame (required): Time aggregation period: per_hour, per_day, per_month, custom_range
start_date (conditional): Start date for analysis (required for custom_range). Format: YYYY-MM-DD
end_date (conditional): End date for analysis (required for custom_range). Format: YYYY-MM-DD
is_purchase (optional): Filter by purchase events: true, false, all (default: all)
page (optional): Page number for pagination (default: 1)
limit (optional): Results per page, max 100 (default: 50)

Success Response (200 OK):

{
  "success": "boolean",
  "message": "string",
  "data": {
    "campaign_id": "UUID",
    "time_frame": "string",
    "instances": [
      {
        "instance_id": "UUID",
        "insider_id": "UUID",
        "is_purchase": "boolean",
        "purchased_insider_id": "UUID or null",
        "timestamp": "ISO 8601 timestamp",
        "revenue": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "purchase_instances": "number",
      "non_purchase_instances": "number",
      "total_revenue": "number",
      "conversion_rate": "number (0.0-1.0)"
    }
  },
  "pagination": {
    "page": "number",
    "limit": "number",
    "total": "number",
    "totalPages": "number",
    "hasNext": "boolean",
    "hasPrevious": "boolean"
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Specific Error Cases:

400: Invalid UUID format for campaign_id
400: Invalid time_frame parameter (must be per_hour, per_day, per_month, or custom_range)
400: Missing start_date for custom_range
400: Missing end_date for custom_range
400: Invalid date format (must be YYYY-MM-DD)
400: End date must be after start_date
400: Date range too large (exceeds maximum allowed period)
400: Invalid is_purchase parameter (must be true, false, or all)
400: Invalid page number (must be positive integer)
400: Invalid limit value (must be 1-100)
404: Campaign not found with the specified campaign_id
403: Insufficient permissions to view campaign analytics
422: No analytics data available for the specified time period