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

Events sent with your API key are treated as trusted server-side events: they are not filtered by User-Agent or IP heuristics, so default curl and HTTP-library User-Agents work. In a few cases the event is received but intentionally not processed (for example when the request carries a preview or localhost url, or when a plan allowance is reached). The response then keeps HTTP 200 and includes a filtered reason code, so you can tell it apart from a tracked event:

{
  "success": true,
  "event_id": "evt_xyz789",
  "message": "Event received but not processed",
  "filtered": "preview_environment"
}

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

503 Service Unavailable

Returned when SignalBridge could not verify your API key, rate limit, or pixel access because a supporting service was briefly unavailable. Your request was not rejected as invalid, so send it again after the number of seconds in the Retry-After header. Unlike 401, 403, and 404, this response is temporary.

{
  "error": "Service temporarily unavailable"
}

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

​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

​503 Service Unavailable

​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

503 Service Unavailable

Rate Limits

Webhooks

Available Events

Webhook Payload

Webhook Signature

SDKs

Need Help?