> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalbridgedata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for 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.

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from the [Dashboard](https://www.signalbridgedata.com/dashboard/settings/api).

## Quick Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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));
  ?>
  ```
</CodeGroup>

## 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:**

```json theme={null}
{
  "success": true,
  "event_id": "evt_xyz789",
  "message": "Event tracked successfully"
}
```

### Get Pixel

Retrieve pixel information.

**Endpoint:** `GET /v1/pixels/:pixel_id`

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```javascript theme={null}
{
  "pixel_id": "px_abc123",
  "event_name": "CustomEvent",
  "custom_data": {
    "plan": "premium",
    "duration": "annual"
  }
}
```

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid request",
  "message": "Missing required field: pixel_id"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden",
  "message": "Subscription limit exceeded"
}
```

### 429 Too Many Requests

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

### 500 Internal Server Error

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```javascript theme={null}
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](mailto:support@signalbridgedata.com)
* **Dashboard:** [signalbridgedata.com/dashboard](https://www.signalbridgedata.com/dashboard)
* **Status Page:** [status.signalbridgedata.com](https://status.signalbridgedata.com)