API Reference - SignalBridge

Overview

The SignalBridge API allows you to send tracking events directly from your server, integrate with your backend systems, and manage your pixels programmatically. Base URL: https://api.signalbridgedata.com

Authentication

All API requests require authentication using your API key.

Your API key carries full access to your account. Keep it secure and never expose it in client-side code.

Authorization: Bearer YOUR_API_KEY

Get your API key from the Dashboard.

Quick Example

curl -X POST https://api.signalbridgedata.com/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pixel_id": "px_abc123",
    "event_name": "Purchase",
    "event_id": "evt_xyz789",
    "value": 99.99,
    "currency": "USD",
    "user_data": {
      "email": "customer@example.com",
      "phone": "+1234567890"
    }
  }'

const response = await fetch('https://api.signalbridgedata.com/v1/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pixel_id: 'px_abc123',
    event_name: 'Purchase',
    event_id: 'evt_xyz789',
    value: 99.99,
    currency: 'USD',
    user_data: {
      email: 'customer@example.com',
      phone: '+1234567890'
    }
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.signalbridgedata.com/v1/track',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'pixel_id': 'px_abc123',
        'event_name': 'Purchase',
        'event_id': 'evt_xyz789',
        'value': 99.99,
        'currency': 'USD',
        'user_data': {
            'email': 'customer@example.com',
            'phone': '+1234567890'
        }
    }
)

print(response.json())

<?php
$ch = curl_init('https://api.signalbridgedata.com/v1/track');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'pixel_id' => 'px_abc123',
    'event_name' => 'Purchase',
    'event_id' => 'evt_xyz789',
    'value' => 99.99,
    'currency' => 'USD',
    'user_data' => [
        'email' => 'customer@example.com',
        'phone' => '+1234567890'
    ]
]));

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

print_r(json_decode($response));
?>

API Endpoints

Track Event

Send a tracking event to SignalBridge. Endpoint: POST /v1/track Headers:

Authorization: Bearer YOUR_API_KEY (required)
Content-Type: application/json (required)

Body Parameters:

Parameter	Type	Required	Description
`pixel_id`	string	Yes	Your pixel ID (e.g., `px_abc123`)
`event_name`	string	Yes	Event name (e.g., `Purchase`, `Lead`)
`event_id`	string	No	Unique event ID for deduplication
`value`	number	No	Event value (e.g., purchase amount)
`currency`	string	No	Currency code (e.g., `USD`, `EUR`)
`user_data`	object	No	User information for enhanced matching
`timestamp`	string	No	ISO 8601 timestamp (defaults to now)
`url`	string	No	Page URL where event occurred
`referrer`	string	No	Referrer URL

User Data Fields:

Field	Type	Description
`email`	string	User email (will be hashed)
`phone`	string	Phone number in E.164 format
`first_name`	string	First name
`last_name`	string	Last name
`city`	string	City
`state`	string	State/province
`zip`	string	Postal code
`country`	string	Country code (ISO 3166-1 alpha-2)
`external_id`	string	Your internal user ID

Response:

{
  "success": true,
  "event_id": "evt_xyz789",
  "message": "Event tracked successfully"
}

Get Pixel

Retrieve pixel information. Endpoint: GET /v1/pixels/:pixel_id Response:

{
  "id": "px_abc123",
  "name": "My Website Pixel",
  "domain": "example.com",
  "tracking_domain": "tracking.example.com",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

List Events

Get recent events for a pixel. Endpoint: GET /v1/pixels/:pixel_id/events Query Parameters:

Parameter	Type	Description
`limit`	number	Number of events to return (max 100)
`offset`	number	Pagination offset
`event_name`	string	Filter by event name
`start_date`	string	Filter by start date (ISO 8601)
`end_date`	string	Filter by end date (ISO 8601)

Response:

{
  "events": [
    {
      "event_id": "evt_xyz789",
      "event_name": "Purchase",
      "value": 99.99,
      "currency": "USD",
      "timestamp": "2024-01-15T10:30:00Z",
      "status": "processed"
    }
  ],
  "total": 1250,
  "limit": 50,
  "offset": 0
}

Standard Events

SignalBridge supports these standard event names:

Event Name	Description	Recommended Parameters
`PageView`	User viewed a page	`url`, `title`
`ViewContent`	User viewed a product/content	`value`, `currency`
`AddToCart`	User added item to cart	`value`, `currency`
`InitiateCheckout`	User started checkout	`value`, `currency`
`AddPaymentInfo`	User added payment method	`value`, `currency`
`Purchase`	User completed purchase	`value`, `currency`, `user_data`
`Lead`	User submitted lead form	`user_data`
`CompleteRegistration`	User signed up	`user_data`
`Search`	User performed search	`search_string`
`Subscribe`	User subscribed	`user_data`

Custom Events

You can also track custom events:

{
  "pixel_id": "px_abc123",
  "event_name": "CustomEvent",
  "custom_data": {
    "plan": "premium",
    "duration": "annual"
  }
}

Error Responses

400 Bad Request

{
  "error": "Invalid request",
  "message": "Missing required field: pixel_id"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Subscription limit exceeded"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 60
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Rate Limits

API Access is available for Pro, Ultra, and Enterprise tiers only.

Plan	Requests per Minute	Daily Limit
Pro	500	720,000
Ultra	2,000	2,880,000
Enterprise	5,000	7,200,000

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642252800

Webhooks

SignalBridge can send webhooks for important events:

Available Events

event.tracked - New event was tracked
event.forwarded - Event was forwarded to platform
pixel.created - New pixel was created
pixel.updated - Pixel was updated
subscription.updated - Subscription changed

Webhook Payload

{
  "event": "event.tracked",
  "data": {
    "pixel_id": "px_abc123",
    "event_name": "Purchase",
    "event_id": "evt_xyz789",
    "value": 99.99,
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "webhook_id": "wh_xyz789",
  "timestamp": "2024-01-15T10:30:01Z"
}

Webhook Signature

All webhooks include a signature header for verification:

X-SignalBridge-Signature: sha256=abc123...

Verify the signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

SDKs

Official SDKs coming soon:

JavaScript/TypeScript
Python
PHP
Ruby
Go

Need Help?

Email: support@signalbridgedata.com
Dashboard: signalbridgedata.com/dashboard
Status Page: status.signalbridgedata.com

​Overview

​Authentication

​Quick Example

​API Endpoints

​Track Event

​Get Pixel

​List Events

​Standard Events

​Custom Events

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

​Rate Limits

​Webhooks

​Available Events

​Webhook Payload

​Webhook Signature

​SDKs

​Need Help?

Overview

Authentication

Quick Example

API Endpoints

Track Event

Get Pixel

List Events

Standard Events

Custom Events

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Rate Limits

Webhooks

Available Events

Webhook Payload

Webhook Signature

SDKs

Need Help?