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

Production
https://api.tandembeam.com
Development
https://dev.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.

Core Endpoints

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"
}

Response

{
  "success": true,
  "event_id": "unique-event-id-123",
  "trace_id": "trace-abc123",
  "platforms_sent": ["meta", "google_ads", "tiktok"],
  "message": "Event processed successfully"
}
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.

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 9 platforms: The contact event is mapped to platform-specific equivalents across Meta, Google Ads, LinkedIn, TikTok, Pinterest, Reddit, Twitter/X, Bing Ads, and GA4.

Next Steps

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

ClickBeam Integration → Event Types Reference