API Reference

Complete API documentation for the Tandem Beam platform. This reference covers all endpoints, authentication, request formats, and response structures.

REST API

JSON Format

v1.0

Authentication

The Tandem Beam API uses Bearer token authentication. Include your API token in the Authorization header for all requests.

Authentication Header

Authorization: Bearer your_api_token_here

Base URL

https://api.tandembeam.com

Recommended: CNAME Setup for ClickBeam

For optimal performance and tracking reliability, we recommend setting up a CNAME record for ClickBeam API calls.

Benefits

• First-party context: API calls appear to come from your domain
• Improved reliability: Reduces chance of ad-blocker interference
• Better cookie handling: First-party cookies have fewer restrictions
• CORS elimination: Same-origin requests avoid cross-domain issues

Example CNAME Configuration

Your Domain DNS:


                                            beam.yourdomain.com → CNAME → api.tandembeam.com

ClickBeam will then use:


                                            https://beam.yourdomain.com/api/track

Note: CNAME is recommended but not required. ClickBeam works with direct api.tandembeam.com calls if CNAME setup is not possible. Configure your CNAME preference in ClickBeam deployment settings.

Event Tracking API

POST

/api/track

Core Tracking

Send tracking events to the Tandem Beam platform. This is the primary endpoint for event ingestion.

Request Body

{
  "event_name": "purchase",
  "event_id": "unique-event-id-123",
  "user_data": {
    "em": "hashed_email_sha256",
    "ph": "hashed_phone_sha256",
    "fn": "hashed_first_name_sha256",
    "ln": "hashed_last_name_sha256"
  },
  "custom_data": {
    "value": 99.99,
    "currency": "USD",
    "content_ids": ["product_123", "product_456"],
    "content_type": "product",
    "num_items": 2
  },
  "event_source_url": "https://example.com/checkout",
  "action_source": "website"
}

Required: browser_data Field

The browser_data object is required for all tracking requests. Requests without this field will return a 422 Validation Error.

SkyBeam/ClickBeam users: This field is automatically populated by the tracking scripts.

Direct API users: You must provide this field manually with the following structure:

"browser_data": {
  "user_agent": "Mozilla/5.0...",
  "screen_resolution": "1920x1080",
  "language": "en-US",
  "timezone": "America/New_York",
  "referrer": "https://google.com",
  "ip": "192.168.1.1"
}

System Context Fields

The tracking API accepts optional context objects that provide additional metadata about the request source.

`browser_data` REQUIRED

Browser and environment information collected at the point of tracking:

"browser_data": {
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "screen_size": "1920x1080",
  "viewport_size": "1440x900",
  "language": "en-US",
  "timezone": "America/New_York",
  "referrer": "https://google.com/search?q=..."
}

`clickbeam` OPTIONAL

Client-side context automatically populated by ClickBeam tracking script:

"clickbeam": {
  "screen_size": "1920x1080",
  "viewport_size": "1440x900"
}

`skybeam` OPTIONAL

Server-side context automatically populated by SkyBeam edge worker:

"skybeam": {
  "worker_region": "DFW",
  "edge_request_id": "abc123def456"
}

Direct API Integration

The clickbeam and skybeam objects are automatically populated by their respective tracking systems. Direct API users should omit these fields and only provide the required browser_data object.

Response

{
  "message": "Event tracked successfully",
  "event_id": 12345,
  "platform_results": {
    "meta": {
      "status": "queued",
      "message": "Event queued for processing"
    },
    "google_ads": {
      "status": "batched",
      "message": "Event added to batch for processing"
    }
  }
}

Response Fields

message - Confirmation message for the API request

event_id - Integer ID of the created event record

platform_results - Object containing status for each destination platform:

status - Either queued (immediate processing) or batched (batch processing enabled)
message - Human-readable status description

Alternative Response Formats

Depending on traffic type and system configuration, the API may return different response structures:

Beam-Only Mode Organic Traffic

Returned when the event is captured but not forwarded to any platforms. This occurs for organic traffic (no platform click IDs present), or when platform configuration is incomplete.

{
  "message": "Event captured by Beam",
  "event_id": 12345,
  "mode": "beam",
  "platforms_forwarded": 0,
  "reason": "Event does not contain platform click IDs (organic traffic)"
}

Possible reasons:

Event does not contain platform click IDs (organic traffic)
All platforms require conversion configuration which is not set up
Event destinations exclude all platforms
No platforms configured

Coordinated Duplicate LASER BEAM

Returned when both SkyBeam (server-side) and ClickBeam (client-side) capture the same event. The first request queues platform jobs; the second request updates coordination metadata only.

{
  "message": "Event coordinated successfully",
  "event_id": 12345,
  "coordinated": true,
  "dual_capture": true,
  "sources": ["skybeam", "clickbeam"],
  "coordination_method": "deduplication_key",
  "platform_results": {}
}

Key fields:

coordinated: true - Event matched an existing event
dual_capture: true - Both tracking systems captured the event
sources - Array of systems that captured the event
platform_results: {} - Empty (already queued by first request)

GET

/api/health

System Health

Check the health status of the Tandem Beam API and its components.

Response

{
  "status": "healthy",
  "timestamp": "2025-08-06T10:30:00Z",
  "version": "1.0.0",
  "components": {
    "database": "healthy",
    "queue": "healthy",
    "cache": "healthy"
  }
}

Standard Event Types

purchase

Transaction completed

add_to_cart

Item added to cart

view_content

Page or product viewed

lead

Lead form submitted

contact

Contact form submission

sign_up

Account registration finished

initiate_checkout

Checkout process started

Error Codes

400

Bad Request

Invalid request format or missing required fields.

401

Unauthorized

Invalid or missing API token. Check your Authorization header.

422

Validation Error

Request data failed validation. Check the error details in the response.

500

Internal Server Error

Something went wrong on our end. Please try again or contact support.

429

Too Many Requests

Rate limit exceeded. Check X-RateLimit-Remaining header and retry after the specified time.

Reporting API

NEW

Extract data and insights from Tandem Beam for analytics integrations, data warehouses, and custom reporting.

Bulk Data Export

High-volume data export endpoints designed for analytics integrations (Snowflake, Domo, custom data warehouses). These APIs support cursor-based pagination for efficient large dataset retrieval and incremental sync patterns.

Authentication & Rate Limiting

Required Headers:

Authorization: Bearer your_api_token
X-Advertiser-ID: your_advertiser_uuid

Rate Limits:

• 10 requests/minute per advertiser
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining
• 429 response when exceeded

GET

/api/export/events

Bulk Export

Export tracking events with cursor-based pagination. Supports incremental sync via updated_since parameter.

Parameters

Parameter	Type	Required	Description
from	date	✓	Start date (YYYY-MM-DD)
to	date	✓	End date (YYYY-MM-DD)
format	string	-	`json` (default) or `csv`
limit	integer	-	Records per page (default: 1000, max: 10000)
cursor	string	-	Pagination cursor from previous response
updated_since	datetime	-	For incremental sync (ISO 8601 format)
event_type	string	-	Filter by event type (e.g., purchase, lead)

Response (JSON)

{
  "data": [
    {
      "id": 12345,
      "event_type": "purchase",
      "event_data": { "value": 99.99, "currency": "USD" },
      "tandem_tracking": { "sources": ["meta", "google"] },
      "created_at": "2025-11-25T10:30:00Z",
      "updated_at": "2025-11-25T10:30:00Z"
    }
  ],
  "meta": {
    "total_in_range": 150000,
    "returned": 1000,
    "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0yNSAxMDozMDowMCIsImlkIjoxMjM0NX0=",
    "has_more": true
  }
}

PII Filtering: Sensitive fields (email, phone, address, etc.) are automatically excluded from event_data. IP addresses and user_data are not included.

Attribution Fields
NEW

Events include pre-computed attribution data for faster analytics queries. Attribution uses a 4-level priority system.

Field	Type	Description
attribution_source	string	Platform or source credited (e.g., "google-ads", "newsletter")
attribution_type	string	Category: paid, organic, email, referral, social, affiliate
attribution_priority	integer	1=click_id, 2=utm, 3=referrer, 4=organic
utm_source	string	UTM source parameter (e.g., "google", "facebook")
utm_medium	string	UTM medium parameter (e.g., "cpc", "email")
utm_campaign	string	UTM campaign parameter (e.g., "brand_2024")

Attribution Priority Hierarchy

Priority 1: Click IDs (gclid, fbclid, ttclid, etc.) - Highest confidence

Priority 2: UTM Parameters - Explicit campaign tagging

Priority 3: Referrer Analysis - External domain detection

Priority 4: Organic - No attribution signals detected

GET

/api/export/sessions

Bulk Export

Export user sessions (LaserBeam sessions) with aggregated metrics. Identity keys are pseudonymized via SHA-256 hashing.

Parameters

Parameter	Type	Required	Description
from	date	✓	Start date for first_seen (YYYY-MM-DD)
to	date	✓	End date for first_seen (YYYY-MM-DD)
format	string	-	`json` (default) or `csv`
limit	integer	-	Records per page (default: 1000, max: 10000)
cursor	string	-	Pagination cursor from previous response
min_events	integer	-	Filter sessions with at least N events

Response (JSON)

{
  "data": [
    {
      "id": "abc123",
      "identity_key_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
      "first_seen": "2025-11-25T08:00:00Z",
      "last_seen": "2025-11-25T10:30:00Z",
      "event_count": 12,
      "page_view_count": 8,
      "conversion_count": 1,
      "total_value": 149.99
    }
  ],
  "meta": {
    "total_in_range": 5000,
    "returned": 1000,
    "cursor": "eyJmaXJzdF9zZWVuIjoiMjAyNS0xMS0yNSAwODowMDowMCIsImlkIjoiYWJjMTIzIn0=",
    "has_more": true
  }
}

Privacy: Identity keys are SHA-256 hashed. Device fingerprints and browser fingerprint details are excluded.

GET

/api/export/platform-logs

Bulk Export

Export platform delivery logs for analyzing success rates, debugging integrations, and tracking platform performance.

Parameters

Parameter	Type	Required	Description
from	date	✓	Start date for sent_at (YYYY-MM-DD)
to	date	✓	End date for sent_at (YYYY-MM-DD)
format	string	-	`json` (default) or `csv`
limit	integer	-	Records per page (default: 1000, max: 10000)
cursor	string	-	Pagination cursor from previous response
platform	string	-	Filter by platform slug (e.g., meta, google-ads)
status_code	integer	-	Filter by HTTP status code (e.g., 200, 400)

Response (JSON)

{
  "data": [
    {
      "id": "uuid-here",
      "platform_id": "platform-uuid",
      "platform_slug": "meta",
      "advertiser_platform_id": "ap-uuid",
      "tracking_event_id": 12345,
      "event_name": "Purchase",
      "vendor_id_used": "fbclid_abc123",
      "attribution_source": "cookie",
      "status_code": 200,
      "sent_at": "2025-11-25T10:30:00Z",
      "is_success": true
    }
  ],
  "meta": {
    "total_in_range": 25000,
    "returned": 1000,
    "cursor": "eyJzZW50X2F0IjoiMjAyNS0xMS0yNSAxMDozMDowMCIsImlkIjoidXVpZC1oZXJlIn0=",
    "has_more": true
  }
}

Security: Request payloads and response bodies are excluded as they may contain PII or sensitive API data.

Cursor-Based Pagination

Export APIs use cursor-based pagination for efficient retrieval of large datasets. Unlike offset pagination, cursor pagination maintains consistent performance regardless of how deep you paginate.

Example: Paginating Through All Events

# First request
curl -X GET "https://api.tandembeam.com/api/export/events?from=2025-11-01&to=2025-11-30&limit=1000" \
  -H "Authorization: Bearer your_api_token" \
  -H "X-Advertiser-ID: your_advertiser_uuid"

# Response includes cursor for next page
# "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0yNSAxMDozMDowMCIsImlkIjoxMjM0NX0="
# "has_more": true

# Second request (use cursor from previous response)
curl -X GET "https://api.tandembeam.com/api/export/events?from=2025-11-01&to=2025-11-30&limit=1000&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0yNSAxMDozMDowMCIsImlkIjoxMjM0NX0=" \
  -H "Authorization: Bearer your_api_token" \
  -H "X-Advertiser-ID: your_advertiser_uuid"

# Continue until has_more: false

✓ Benefits

• Consistent O(log n) performance at any depth
• No duplicate or skipped records
• Handles concurrent inserts correctly
• Stateless (cursor contains all context)

ℹ️ Best Practices

• Use limit=10000 for batch jobs
• Store cursor for resume capability
• Check has_more before next request
• Invalid cursors are safely ignored

Incremental Sync Pattern

For data warehouse integrations, use updated_since to fetch only records modified since your last sync.

# Initial full sync
curl -X GET "https://api.tandembeam.com/api/export/events?from=2025-01-01&to=2025-11-30" \
  -H "Authorization: Bearer your_api_token" \
  -H "X-Advertiser-ID: your_advertiser_uuid"
# Store timestamp: 2025-11-30T23:59:59Z

# Next day: incremental sync (only changed records)
curl -X GET "https://api.tandembeam.com/api/export/events?from=2025-01-01&to=2025-12-01&updated_since=2025-11-30T23:59:59Z" \
  -H "Authorization: Bearer your_api_token" \
  -H "X-Advertiser-ID: your_advertiser_uuid"
# Returns only records updated after the timestamp

Tip: Store the sync timestamp in your data warehouse metadata table. Use UPSERT logic based on event ID to handle updates to existing records.

JSON vs CSV Format

{ } JSON Format

✓ Includes metadata (total_in_range, cursor, has_more)
✓ Nested objects preserved (event_data, tandem_tracking)
✓ Better for API-to-API integrations
○ Slightly larger payload size

Best for: Programmatic integrations, when you need pagination metadata

CSV CSV Format

✓ Streaming download (memory efficient)
✓ Direct import to Snowflake, BigQuery, Excel
✓ UTF-8 BOM included for Excel compatibility
○ Nested objects JSON-stringified

Best for: Data warehouse imports, large single exports, spreadsheet analysis

CSV Download Example

# Download events as CSV
curl -X GET "https://api.tandembeam.com/api/export/events?from=2025-11-01&to=2025-11-30&format=csv&limit=10000" \
  -H "Authorization: Bearer your_api_token" \
  -H "X-Advertiser-ID: your_advertiser_uuid" \
  -o events_export.csv

# CSV is streamed - suitable for very large exports

Pre-Computed Analytics Reports

Pre-computed analytics reports provide actionable insights that no other analytics tool can offer. Tandem Beam's unique cross-platform tracking enables attribution analysis, platform delivery verification, journey visualization, and traffic quality scoring—all with millisecond precision.

Common Parameters & Rate Limiting

Required Parameters (all endpoints):

Parameter	Type	Description
from	date	Start date (YYYY-MM-DD)
to	date	End date (YYYY-MM-DD)
platform	string	Filter by platform slug (optional)
event_type	string	Filter by event type (optional)
limit	int	Max results 1-1000 (optional)

Rate Limiting & Caching:

• 30 requests/minute per advertiser
• 5-minute cache TTL on all aggregate reports
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining
• 429 response when rate limit exceeded

Response Format:

{ "data": {...}, "meta": { "report_type", "date_range", "generated_at", "cache_ttl_seconds" } }

Attribution Reports

GET

/api/reports/attribution/first-touch

Attribution

Shows which platforms/channels first brought users who later converted. Unique value: See true acquisition sources before platform attribution windows expire.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "click_id_types": ["gclid", "gbraid"],
        "sessions_count": 1250,
        "conversions_count": 87,
        "conversion_rate": 6.96,
        "revenue": 12450.00,
        "avg_time_to_conversion_minutes": 42.3,
        "sample_sessions": ["sess_abc123", "sess_def456"]
      },
      {
        "platform": "meta",
        "click_id_types": ["fbclid"],
        "sessions_count": 890,
        "conversions_count": 52,
        "conversion_rate": 5.84,
        "revenue": 7230.50,
        "avg_time_to_conversion_minutes": 55.1,
        "sample_sessions": ["sess_ghi789"]
      }
    ],
    "summary": {
      "total_sessions": 3200,
      "total_conversions": 195,
      "overall_conversion_rate": 6.09,
      "avg_time_to_conversion_minutes": 48.7,
      "platforms_count": 5
    }
  },
  "meta": {
    "report_type": "first_touch_attribution",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/attribution/last-touch

Attribution

Shows which platform gets credit for the conversion (last touchpoint before conversion). Unique value: Compare against platform-reported attributions.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "conversions_count": 95,
        "revenue": 14200.00,
        "avg_touchpoints_before_conversion": 3.2,
        "attribution_share": 48.72
      },
      {
        "platform": "meta",
        "conversions_count": 58,
        "revenue": 8100.00,
        "avg_touchpoints_before_conversion": 2.8,
        "attribution_share": 29.74
      }
    ],
    "summary": {
      "total_conversions": 195,
      "total_revenue": 28500.00,
      "avg_touchpoints_before_conversion": 3.1,
      "platforms_count": 5
    }
  },
  "meta": {
    "report_type": "last_touch_attribution",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/attribution/multi-touch

Attribution

Full path analysis showing all touchpoints in converting journeys. Unique value: Complete cross-platform journey visualization.

Additional Parameters

limit - Max journeys to analyze (default: 100, max: 1000)

Response

{
  "data": {
    "journey_patterns": [
      {
        "journey_pattern": "google-ads -> direct -> conversion:purchase",
        "frequency": 45,
        "frequency_percentage": 23.08,
        "avg_touchpoints": 4.2,
        "avg_duration_minutes": 125.5
      },
      {
        "journey_pattern": "meta -> google-ads -> conversion:lead",
        "frequency": 32,
        "frequency_percentage": 16.41,
        "avg_touchpoints": 3.8,
        "avg_duration_minutes": 89.2
      }
    ],
    "platform_contributions": [
      {
        "platform": "google-ads",
        "total_touchpoints": 892,
        "journeys_participated": 156,
        "conversions_influenced": 112,
        "touchpoint_share": 42.5
      },
      {
        "platform": "meta",
        "total_touchpoints": 634,
        "journeys_participated": 98,
        "conversions_influenced": 78,
        "touchpoint_share": 30.2
      }
    ],
    "summary": {
      "total_journeys_analyzed": 195,
      "unique_patterns": 23,
      "avg_touchpoints_per_journey": 3.8,
      "avg_journey_duration_minutes": 112.4
    }
  },
  "meta": {
    "report_type": "multi_touch_attribution",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/attribution/platform-comparison

Attribution

Compare what platforms claim vs what Tandem Beam tracked. Unique value: Audit platform attribution claims with delivery proof.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "platform_name": "Google Ads",
        "tandem_tracked": {
          "total_events_sent": 2450,
          "successful_deliveries": 2398,
          "delivery_success_rate": 97.88,
          "conversions_sent": 95,
          "conversions_delivered": 93
        },
        "attribution": {
          "events_attributed_to_platform": 1890,
          "conversions_attributed_to_platform": 87,
          "using_persisted_attribution": true
        },
        "utm_breakdown": [
          {"utm_source": "google", "utm_medium": "cpc", "count": 1200},
          {"utm_source": "google", "utm_medium": "display", "count": 300}
        ],
        "platform_reported": {
          "_note": "External data import coming soon",
          "claimed_conversions": null,
          "claimed_revenue": null
        },
        "comparison": {
          "delivery_verification_rate": 97.88,
          "attribution_to_delivery_ratio": 0.94
        }
      }
    ],
    "summary": {
      "platforms_active": 5,
      "total_events_sent": 8500,
      "total_successful_deliveries": 8320,
      "overall_delivery_rate": 97.88,
      "external_import_status": "not_configured"
    }
  },
  "meta": {
    "report_type": "platform_comparison",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "external_import_available": false,
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

New in v1.1: Platform comparison now includes:

utm_breakdown - Top UTM sources/mediums per platform
attribution.using_persisted_attribution - Uses pre-computed attribution fields

GET

/api/reports/attribution/utm-breakdown

NEW

Analyzes conversions by UTM parameters for campaign-level insights. Unique value: See which campaigns and sources drive conversions beyond platform attribution.

Query Parameters

from (required) - Start date (YYYY-MM-DD)
to (required) - End date (YYYY-MM-DD)

Response

{
  "data": {
    "by_utm_source": [
      {
        "utm_source": "google",
        "events": 1250,
        "sessions": 450,
        "conversions": 45,
        "conversion_rate": 10.0,
        "top_campaigns": { "brand_2024": 25, "remarketing": 12 }
      },
      {
        "utm_source": "facebook",
        "events": 890,
        "sessions": 320,
        "conversions": 28,
        "conversion_rate": 8.75,
        "top_campaigns": { "lookalike_q4": 15, "retargeting": 13 }
      }
    ],
    "summary": {
      "total_events_with_utm": 2140,
      "total_conversions": 73,
      "unique_sources": 5,
      "unique_campaigns": 12
    }
  },
  "meta": {
    "report_type": "utm_breakdown",
    "date_range": { "from": "2025-12-01", "to": "2025-12-19" },
    "generated_at": "2025-12-19T15:30:00Z"
  }
}

Use Case: Identify which UTM-tagged campaigns drive the most conversions, even when click IDs aren't present (e.g., email campaigns, organic social).

Value Attribution Reports

ROI-focused reports showing revenue and conversion data by platform and campaign. Designed for data warehouse integrations (Snowflake, Domo) and custom dashboards.

GET

/api/reports/value/summary

NEW

Returns aggregate revenue and conversion metrics. Unique value: Single endpoint for all key ROI metrics.

Query Parameters

from (optional) - Start date (YYYY-MM-DD, default: -30 days)
to (optional) - End date (YYYY-MM-DD, default: today)

Response

{
  "data": {
    "total_revenue": 124500.00,
    "total_conversions": 847,
    "conversion_rate": 3.2,
    "avg_order_value": 147.00,
    "total_sessions": 26468
  },
  "meta": {
    "report_type": "value_summary",
    "date_range": { "from": "2025-11-20", "to": "2025-12-20" },
    "currency": "USD",
    "generated_at": "2025-12-20T10:30:00Z"
  }
}

GET

/api/reports/value/by-platform

NEW

Returns revenue and conversion breakdown by advertising platform. Unique value: Compare platform ROI with first-touch or last-touch attribution.

Query Parameters

from (optional) - Start date (YYYY-MM-DD, default: -30 days)
to (optional) - End date (YYYY-MM-DD, default: today)
attribution_model (optional) - first_touch (default) or last_touch

Response

{
  "data": {
    "platforms": [
      {
        "platform": "Google Ads",
        "platform_slug": "google-ads",
        "revenue": 45000.00,
        "conversions": 312,
        "sessions": 7609,
        "conversion_rate": 4.1,
        "avg_order_value": 144.23
      },
      {
        "platform": "Meta",
        "platform_slug": "meta",
        "revenue": 38500.00,
        "conversions": 267,
        "sessions": 7026,
        "conversion_rate": 3.8,
        "avg_order_value": 144.19
      }
    ],
    "totals": {
      "revenue": 124500.00,
      "conversions": 847,
      "sessions": 26468,
      "conversion_rate": 3.2,
      "avg_order_value": 147.00
    }
  },
  "meta": {
    "report_type": "value_by_platform",
    "attribution_model": "first_touch",
    "date_range": { "from": "2025-11-20", "to": "2025-12-20" },
    "currency": "USD",
    "generated_at": "2025-12-20T10:30:00Z"
  }
}

GET

/api/reports/value/top-campaigns

NEW

Returns campaigns ranked by revenue with platform attribution. Unique value: Identify top-performing campaigns across all platforms.

Query Parameters

from (optional) - Start date (YYYY-MM-DD, default: -30 days)
to (optional) - End date (YYYY-MM-DD, default: today)
limit (optional) - Max campaigns to return (1-100, default: 20)

Response

{
  "data": {
    "campaigns": [
      {
        "utm_source": "facebook",
        "utm_medium": "cpc",
        "utm_campaign": "holiday_sale_2025",
        "platform": "Meta",
        "platform_slug": "meta",
        "revenue": 12500.00,
        "conversions": 87
      },
      {
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "brand_awareness",
        "platform": "Google Ads",
        "platform_slug": "google-ads",
        "revenue": 9800.00,
        "conversions": 65
      }
    ],
    "total_campaigns": 45
  },
  "meta": {
    "report_type": "top_campaigns",
    "date_range": { "from": "2025-11-20", "to": "2025-12-20" },
    "limit": 20,
    "currency": "USD",
    "generated_at": "2025-12-20T10:30:00Z"
  }
}

Use Case: Feed into Snowflake/Domo dashboards to identify which campaigns deliver the best ROI across all advertising platforms.

Platform Performance Reports

GET

/api/reports/platform/delivery

Platform

Proves events actually reached platforms with full audit trail. Unique value: No other tool can show delivery success with actual payloads.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "meta",
        "platform_name": "Meta",
        "total_events_sent": 3200,
        "successful_deliveries": 3150,
        "failed_deliveries": 50,
        "server_errors": 12,
        "success_rate": 98.44,
        "error_breakdown": {
          "400": 28,
          "401": 5,
          "429": 5,
          "500": 12
        }
      }
    ],
    "sample_failures": [
      {
        "id": "log-uuid-123",
        "platform": "meta",
        "event_name": "PURCHASE",
        "status_code": 400,
        "sent_at": "2025-11-30T15:42:00Z"
      }
    ],
    "summary": {
      "total_events_sent": 8500,
      "total_successful": 8320,
      "total_failed": 180,
      "overall_success_rate": 97.88,
      "platforms_active": 5
    }
  },
  "meta": {
    "report_type": "platform_delivery",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "unique_value": "Full delivery verification with audit trail - unavailable from any other analytics tool",
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/platform/response-times

Platform

Analyzes platform API performance with millisecond precision. Unique value: Compare platform API performance across all your integrations.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "meta",
        "platform_name": "Meta",
        "timing": {
          "avg_response_ms": 245.32,
          "min_response_ms": 89.00,
          "max_response_ms": 1250.00,
          "sample_count": 3200
        },
        "by_event_type": [
          { "event_type": "PURCHASE", "count": 95 },
          { "event_type": "LEAD", "count": 450 },
          { "event_type": "PAGE_VIEW", "count": 2655 }
        ],
        "by_hour": [
          { "hour": 9, "avg_response_ms": 198.5, "count": 450 },
          { "hour": 10, "avg_response_ms": 267.2, "count": 520 },
          { "hour": 14, "avg_response_ms": 312.1, "count": 680 }
        ],
        "events_processed": 3200
      }
    ],
    "summary": {
      "platforms_measured": 5,
      "total_timing_samples": 8500,
      "overall_avg_response_ms": 278.45,
      "fastest_platform": "google-ads"
    }
  },
  "meta": {
    "report_type": "platform_response_times",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "unique_value": "Millisecond-precision API timing across all platforms",
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/platform/correlation

Platform

Shows how the same event was delivered across all configured platforms. Unique value: Proof of unified tracking - same event to all platforms.

Response

{
  "data": {
    "correlated_events": [
      {
        "event_id": 12345,
        "event_type": "purchase",
        "event_timestamp": "2025-11-30T14:22:00Z",
        "platforms_count": 3,
        "all_successful": true,
        "platforms": {
          "meta": {
            "status_code": 200,
            "is_success": true,
            "sent_at": "2025-11-30T14:22:01Z",
            "vendor_id_used": "fbclid_abc123",
            "attribution_source": "cookie"
          },
          "google-ads": {
            "status_code": 200,
            "is_success": true,
            "sent_at": "2025-11-30T14:22:01Z",
            "vendor_id_used": "gclid_xyz789",
            "attribution_source": "url_param"
          }
        }
      }
    ],
    "platform_correlation_scores": [
      {
        "platform": "meta",
        "events_correlated": 1850,
        "successful": 1820,
        "failed": 30,
        "correlation_success_rate": 98.38
      }
    ],
    "summary": {
      "total_multi_platform_events": 2100,
      "fully_successful_deliveries": 1950,
      "full_correlation_rate": 92.86,
      "platforms_in_correlation": 5,
      "avg_platforms_per_event": 2.8
    }
  },
  "meta": {
    "report_type": "platform_correlation",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "unique_value": "Proof of unified tracking - same event delivered to all platforms",
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

Journey & Funnel Reports

GET

/api/reports/funnel/conversion

Journey

Stage-by-stage conversion analysis with cross-platform visibility. Unique value: See exactly where users drop off with platform context.

Additional Parameters

stages - Comma-separated event types for funnel stages (default: page_view,add_to_cart,initiate_checkout,purchase)

Response

{
  "data": {
    "funnel_stages": [
      {
        "stage": "page_view",
        "stage_number": 1,
        "sessions_at_stage": 5200,
        "sessions_from_previous": null,
        "conversion_rate_from_previous": null,
        "avg_time_from_previous_minutes": null,
        "drop_off_urls": {
          "/products": 1200,
          "/about": 450,
          "/": 380
        },
        "platforms_at_stage": {
          "google-ads": 2100,
          "meta": 1450,
          "organic": 1650
        }
      },
      {
        "stage": "add_to_cart",
        "stage_number": 2,
        "sessions_at_stage": 1800,
        "sessions_from_previous": 1650,
        "conversion_rate_from_previous": 34.62,
        "avg_time_from_previous_minutes": 8.5,
        "drop_off_urls": {
          "/cart": 520,
          "/products/123": 180
        },
        "platforms_at_stage": {
          "google-ads": 780,
          "meta": 520,
          "organic": 500
        }
      },
      {
        "stage": "purchase",
        "stage_number": 4,
        "sessions_at_stage": 195,
        "sessions_from_previous": 180,
        "conversion_rate_from_previous": 32.50,
        "avg_time_from_previous_minutes": 12.3,
        "drop_off_urls": {},
        "platforms_at_stage": {
          "google-ads": 87,
          "meta": 52,
          "organic": 56
        }
      }
    ],
    "summary": {
      "stages_analyzed": 4,
      "top_of_funnel_sessions": 5200,
      "bottom_of_funnel_sessions": 195,
      "overall_conversion_rate": 3.75,
      "biggest_drop_off_stage": {
        "from_stage": "page_view",
        "to_stage": "add_to_cart",
        "drop_off_rate": 65.38,
        "sessions_lost": 3400
      }
    }
  },
  "meta": {
    "report_type": "conversion_funnel",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "stages_used": ["page_view", "add_to_cart", "initiate_checkout", "purchase"],
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/journey/session-timeline

Journey

Detailed event-by-event view of a session with platform delivery status. Unique value: Millisecond-precision timeline with cross-platform verification.

Parameters

session_id - LaserBeam session ID (required if no identity_key)
identity_key - User identity key (required if no session_id)

Response

{
  "data": {
    "session_id": "sess_abc123def456",
    "session_info": {
      "first_seen": "2025-11-30T14:00:00Z",
      "last_seen": "2025-11-30T14:45:00Z",
      "duration_minutes": 45,
      "total_events": 12,
      "is_multi_day": false,
      "identity_discovered_at": "2025-11-30T14:32:00Z"
    },
    "first_touch_attribution": {
      "gclid": "CjwKCAjw...",
      "platform": "google-ads"
    },
    "last_touch_attribution": {
      "gclid": "CjwKCAjw...",
      "platform": "google-ads"
    },
    "timeline": [
      {
        "timestamp": "2025-11-30T14:00:00Z",
        "timestamp_ms": "2025-11-30 14:00:00.123456",
        "event_id": 12340,
        "event_type": "page_view",
        "url": "/products",
        "originating_platform": "google-ads",
        "vendor_ids": { "gclid": "CjwKCAjw..." },
        "platforms_notified": 2,
        "platform_deliveries": [
          {
            "platform_id": "uuid-meta",
            "status_code": 200,
            "is_success": true,
            "sent_at": "2025-11-30T14:00:01Z"
          },
          {
            "platform_id": "uuid-google",
            "status_code": 200,
            "is_success": true,
            "sent_at": "2025-11-30T14:00:01Z"
          }
        ],
        "is_conversion": false,
        "event_data_summary": { "path": "/products" }
      },
      {
        "timestamp": "2025-11-30T14:32:00Z",
        "timestamp_ms": "2025-11-30 14:32:00.789012",
        "event_id": 12345,
        "event_type": "purchase",
        "url": "/checkout/complete",
        "originating_platform": "google-ads",
        "vendor_ids": { "gclid": "CjwKCAjw..." },
        "platforms_notified": 2,
        "platform_deliveries": [
          {
            "platform_id": "uuid-meta",
            "status_code": 200,
            "is_success": true,
            "sent_at": "2025-11-30T14:32:01Z"
          }
        ],
        "is_conversion": true,
        "event_data_summary": { "path": "/checkout/complete", "value": 149.99 }
      }
    ]
  },
  "meta": {
    "sessions_found": 1,
    "generated_at": "2025-12-01T10:30:00Z"
  }
}

GET

/api/reports/funnel/drop-off

Journey

Identifies where and why users abandon their journey. Unique value: Correlates drop-offs with platform issues and timing.

Response

{
  "data": {
    "exit_pages": {
      "/products": 1200,
      "/cart": 520,
      "/about": 450,
      "/pricing": 380
    },
    "exit_event_types": {
      "page_view": 2100,
      "add_to_cart": 450,
      "view_content": 320
    },
    "session_duration_distribution": {
      "< 1 min": 1250,
      "1-5 min": 890,
      "5-15 min": 520,
      "15-30 min": 180,
      "30+ min": 65
    },
    "event_count_distribution": {
      "1 event": 1450,
      "2-3 events": 980,
      "4-5 events": 320,
      "6+ events": 155
    },
    "hourly_pattern": [0, 12, 25, 18, 8, 15, 45, 89, 156, 234, 287, 312, 298, 278, 256, 234, 198, 167, 145, 123, 98, 67, 34, 15],
    "by_platform": {
      "google-ads": 1200,
      "meta": 890,
      "organic": 815
    },
    "platform_errors_correlation": {
      "meta": 28,
      "google-ads": 12
    },
    "summary": {
      "total_non_converting_sessions": 2905,
      "avg_session_duration_minutes": 4.2,
      "avg_events_before_drop_off": 2.1,
      "bounce_rate_equivalent": 49.91,
      "peak_drop_off_hour": 11
    }
  },
  "meta": {
    "report_type": "drop_off_analysis",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

Engagement Reports

GET

/api/reports/engagement/time-to-conversion

Engagement

Analyzes how long it takes from first touch to conversion. Unique value: Precise timing across the entire cross-platform journey.

Response

{
  "data": {
    "by_conversion_type": [
      { "conversion_type": "purchase", "count": 95, "avg_time_minutes": 125.4 },
      { "conversion_type": "lead", "count": 78, "avg_time_minutes": 45.2 },
      { "conversion_type": "sign_up", "count": 22, "avg_time_minutes": 18.9 }
    ],
    "by_platform": [
      { "platform": "google-ads", "conversions": 87, "avg_time_minutes": 98.5 },
      { "platform": "meta", "conversions": 52, "avg_time_minutes": 112.3 },
      { "platform": "organic", "conversions": 56, "avg_time_minutes": 145.8 }
    ],
    "by_touchpoint_count": [
      { "touchpoint_range": "1 touchpoint", "conversions": 35, "avg_time_minutes": 12.5 },
      { "touchpoint_range": "2-3 touchpoints", "conversions": 78, "avg_time_minutes": 68.2 },
      { "touchpoint_range": "4-5 touchpoints", "conversions": 52, "avg_time_minutes": 145.6 },
      { "touchpoint_range": "6-10 touchpoints", "conversions": 25, "avg_time_minutes": 312.4 },
      { "touchpoint_range": "10+ touchpoints", "conversions": 5, "avg_time_minutes": 520.1 }
    ],
    "distribution": {
      "< 1 hour": 45,
      "1-24 hours": 78,
      "1-7 days": 52,
      "7-30 days": 18,
      "30+ days": 2
    },
    "summary": {
      "total_conversions": 195,
      "avg_time_minutes": 98.7,
      "median_time_minutes": 72.0,
      "fastest_conversion_minutes": 3,
      "slowest_conversion_minutes": 2880
    }
  },
  "meta": {
    "report_type": "time_to_conversion",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/engagement/sessions

Engagement

Quality metrics for sessions across various dimensions. Unique value: Multi-day session tracking and identity resolution metrics.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "sessions": 1250,
        "avg_duration_minutes": 8.5,
        "avg_events_per_session": 4.2,
        "identification_rate": 15.2
      },
      {
        "platform": "meta",
        "sessions": 890,
        "avg_duration_minutes": 6.8,
        "avg_events_per_session": 3.5,
        "identification_rate": 12.1
      }
    ],
    "duration_distribution": {
      "< 1 min": 1250,
      "1-5 min": 1450,
      "5-15 min": 890,
      "15-30 min": 320,
      "30-60 min": 180,
      "60+ min": 110
    },
    "events_distribution": {
      "1 event": 1650,
      "2-3 events": 1200,
      "4-5 events": 650,
      "6-10 events": 420,
      "10+ events": 280
    },
    "summary": {
      "total_sessions": 4200,
      "avg_duration_minutes": 7.2,
      "avg_events_per_session": 3.8,
      "multi_day_sessions_count": 85,
      "multi_day_sessions_pct": 2.02,
      "identified_sessions_count": 550,
      "identified_sessions_pct": 13.1,
      "avg_time_to_identification_minutes": 42.5
    }
  },
  "meta": {
    "report_type": "session_engagement",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/engagement/velocity

Engagement

Analyzes event volume and patterns over time. Unique value: Detect anomalies and understand traffic patterns.

Response

{
  "data": {
    "daily_breakdown": [
      { "date": "2025-11-01", "count": 2850 },
      { "date": "2025-11-02", "count": 2120 },
      { "date": "2025-11-03", "count": 3450 },
      { "date": "2025-11-29", "count": 8520 },
      { "date": "2025-11-30", "count": 3200 }
    ],
    "hourly_breakdown": {
      "0": 120, "1": 85, "2": 45, "3": 32, "4": 28, "5": 45,
      "6": 156, "7": 345, "8": 520, "9": 780, "10": 890, "11": 920,
      "12": 850, "13": 780, "14": 820, "15": 756, "16": 680, "17": 590,
      "18": 450, "19": 380, "20": 320, "21": 280, "22": 220, "23": 165
    },
    "event_type_mix": {
      "page_view": 65000,
      "add_to_cart": 8500,
      "view_content": 12000,
      "purchase": 950,
      "lead": 780
    },
    "platform_source_mix": {
      "google-ads": 35000,
      "meta": 22000,
      "organic": 28000,
      "linkedin": 2230
    },
    "anomalies_detected": [
      {
        "date": "2025-11-29",
        "count": 8520,
        "type": "spike",
        "ratio": 2.85
      }
    ],
    "summary": {
      "total_events": 87230,
      "days_in_range": 30,
      "avg_events_per_day": 2908,
      "peak_day": "2025-11-29",
      "peak_day_count": 8520,
      "lowest_day": "2025-11-03",
      "lowest_day_count": 1450,
      "peak_hours": [11],
      "anomalies_count": 1
    }
  },
  "meta": {
    "report_type": "event_velocity",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

Identity & Quality Reports

GET

/api/reports/identity/resolution

Identity

Tracks anonymous to identified user conversion. Unique value: See exactly when and where users reveal their identity.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "total_sessions": 1250,
        "identified_sessions": 190,
        "identification_rate": 15.2
      },
      {
        "platform": "meta",
        "total_sessions": 890,
        "identified_sessions": 108,
        "identification_rate": 12.13
      }
    ],
    "identification_pages": {
      "/contact": 145,
      "/checkout": 120,
      "/signup": 95,
      "/quote-request": 78,
      "/newsletter": 62
    },
    "form_types": {
      "lead": 223,
      "contact": 145,
      "purchase": 120,
      "signup": 95,
      "other": 17
    },
    "summary": {
      "total_sessions": 4200,
      "identified_sessions": 550,
      "identification_rate": 13.1,
      "avg_events_before_identification": 3.8,
      "avg_time_to_identification_minutes": 42.5
    }
  },
  "meta": {
    "report_type": "identity_resolution",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/identity/vendor-evolution

Identity

Tracks how platform IDs accumulate through the journey. Unique value: Shows cross-platform ID stitching in action.

Response

{
  "data": {
    "examples": [
      {
        "session_id": "sess_abc123",
        "total_events": 12,
        "platforms_with_ids": ["google-ads", "meta"],
        "platform_count": 2,
        "first_seen": "2025-11-30T14:00:00Z",
        "last_seen": "2025-11-30T14:45:00Z"
      },
      {
        "session_id": "sess_def456",
        "total_events": 8,
        "platforms_with_ids": ["google-ads", "meta", "linkedin"],
        "platform_count": 3,
        "first_seen": "2025-11-30T10:00:00Z",
        "last_seen": "2025-11-30T11:20:00Z"
      }
    ],
    "platform_coverage": [
      { "platform": "google-ads", "sessions_with_id": 1250, "coverage_rate": 62.5 },
      { "platform": "meta", "sessions_with_id": 890, "coverage_rate": 44.5 },
      { "platform": "linkedin", "sessions_with_id": 320, "coverage_rate": 16.0 }
    ],
    "id_accumulation_distribution": {
      "No IDs": 450,
      "1 ID": 1200,
      "2-3 IDs": 280,
      "4+ IDs": 70
    },
    "summary": {
      "sessions_analyzed": 2000,
      "sessions_with_evolution_data": 1830,
      "avg_platforms_per_session": 1.8,
      "platforms_tracked": 5
    }
  },
  "meta": {
    "report_type": "vendor_id_evolution",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "unique_value": "Cross-platform ID stitching visualization",
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

GET

/api/reports/quality/traffic

Quality

Assesses traffic quality by source with scoring. Unique value: Correlate source with conversion quality and engagement.

Response

{
  "data": {
    "by_platform": [
      {
        "platform": "google-ads",
        "sessions_count": 1250,
        "conversion_rate": 6.96,
        "identification_rate": 15.2,
        "bounce_rate": 35.2,
        "avg_events_per_session": 4.2,
        "avg_time_on_site_minutes": 8.5,
        "quality_score": 72.5,
        "quality_rating": "Good"
      },
      {
        "platform": "meta",
        "sessions_count": 890,
        "conversion_rate": 5.84,
        "identification_rate": 12.1,
        "bounce_rate": 42.1,
        "avg_events_per_session": 3.5,
        "avg_time_on_site_minutes": 6.8,
        "quality_score": 58.2,
        "quality_rating": "Average"
      },
      {
        "platform": "organic",
        "sessions_count": 2060,
        "conversion_rate": 2.72,
        "identification_rate": 8.5,
        "bounce_rate": 52.4,
        "avg_events_per_session": 2.8,
        "avg_time_on_site_minutes": 4.2,
        "quality_score": 38.5,
        "quality_rating": "Below Average"
      }
    ],
    "summary": {
      "total_sessions": 4200,
      "total_conversions": 195,
      "overall_conversion_rate": 4.64,
      "overall_identification_rate": 13.1,
      "overall_bounce_rate": 45.2,
      "highest_quality_platform": "google-ads",
      "lowest_quality_platform": "organic",
      "platforms_analyzed": 5
    }
  },
  "meta": {
    "report_type": "traffic_quality",
    "date_range": { "from": "2025-11-01", "to": "2025-11-30" },
    "generated_at": "2025-12-01T10:30:00Z",
    "cache_ttl_seconds": 300
  }
}

Quality Score Formula: Conversion rate (40%) + Identification rate (20%) + Engagement depth (20%) + Time on site (10%) + Inverse bounce rate (10%)

Code Examples

JavaScript (Fetch)

fetch('https://api.tandembeam.com/api/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_token_here'
  },
  body: JSON.stringify({
    event_name: 'purchase',
    user_data: {
      em: 'hashed_email_here'
    },
    custom_data: {
      value: 99.99,
      currency: 'USD'
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));

PHP (cURL)

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.tandembeam.com/api/track',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: Bearer your_api_token_here'
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'event_name' => 'purchase',
    'user_data' => [
      'em' => 'hashed_email_here'
    ],
    'custom_data' => [
      'value' => 99.99,
      'currency' => 'USD'
    ]
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

Contact Event Example

// Contact form submission tracking
fetch('https://api.tandembeam.com/api/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_token_here'
  },
  body: JSON.stringify({
    event_name: 'contact',
    event_id: 'contact_' + Date.now(),
    user_data: {
      em: 'hashed_email_sha256',
      ph: 'hashed_phone_sha256',
      fn: 'hashed_firstname_sha256',
      ln: 'hashed_lastname_sha256'
    },
    custom_data: {
      form_type: 'contact_us',
      message_subject: 'Product Inquiry',
      referrer: document.referrer
    },
    event_source_url: window.location.href,
    action_source: 'website'
  })
})
.then(response => response.json())
.then(data => console.log('Contact event tracked:', data));

Supported by all 10 platforms: The contact event is mapped to platform-specific equivalents across Meta, Google Ads, LinkedIn, TikTok, Pinterest, Reddit, Twitter/X, Bing Ads, GA4, and DEV+NULL (test platform).

Next Steps

Ready to start implementing? Check out our implementation guides and code examples.

ClickBeam Integration → Event Types Reference

API Reference

On This Page

Authentication

Authentication Header

Base URL

Recommended: CNAME Setup for ClickBeam

Benefits

Example CNAME Configuration

Event Tracking API

Request Body

Required: browser_data Field

System Context Fields

browser_data REQUIRED

clickbeam OPTIONAL

skybeam OPTIONAL

Direct API Integration

Response

Response Fields

Alternative Response Formats

Beam-Only Mode Organic Traffic

Coordinated Duplicate LASER BEAM

Response

Standard Event Types

Error Codes

Reporting API

Bulk Data Export

Authentication & Rate Limiting

Parameters

Response (JSON)

Attribution Fields NEW

Attribution Priority Hierarchy

Parameters

Response (JSON)

Parameters

Response (JSON)

Cursor-Based Pagination

Example: Paginating Through All Events

✓ Benefits

ℹ️ Best Practices

Incremental Sync Pattern

JSON vs CSV Format

{ } JSON Format

CSV CSV Format

CSV Download Example

Pre-Computed Analytics Reports

Common Parameters & Rate Limiting

Attribution Reports

Response

Response

Additional Parameters

Response

Response

Query Parameters

Response

Value Attribution Reports

Query Parameters

Response

Query Parameters

Response

Query Parameters

Response

Platform Performance Reports

Response

Response

Response

Journey & Funnel Reports

Additional Parameters

Response

Parameters

Response

Response

Engagement Reports

Response

Response

Response

Identity & Quality Reports

Response

Response

Response

Code Examples

`browser_data` REQUIRED

`clickbeam` OPTIONAL

`skybeam` OPTIONAL

Attribution Fields
NEW