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
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"
}
}'
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 |
| 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 |
{
"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) |
{
"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 |
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 trackedevent.forwarded - Event was forwarded to platformpixel.created - New pixel was createdpixel.updated - Pixel was updatedsubscription.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...
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?
