API Integration Guide

Every API request requires an API key. Generate one from your dashboard under Settings > API Keys. You can create multiple keys with different permissions for different environments.

Include your API key in the Authorization header as a Bearer token on every request.

curl -X GET https://api.tonicpow.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API keys are scoped to your account. Keep them out of client-side code. Use environment variables on your server and never commit keys to version control.

The campaigns API lets you create, read, update, and manage campaigns programmatically. Here are the core endpoints:

curl -X POST https://api.tonicpow.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Promo",
    "targetUrl": "https://example.com/summer",
    "advertiserId": "adv_abc123",
    "payoutModel": "CPC",
    "payoutRate": 0.005
  }'

For CPA campaigns, you need to notify TonicPow when a conversion happens. This can be done client-side with a JavaScript pixel or server-side with an API call.

Client-side pixel: When a visitor arrives via a TonicPow link, a session ID is stored in the browser. Use it to fire a conversion when the user completes the desired action:

// Track a conversion (client-side)
fetch('https://api.tonicpow.com/v1/conversions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goalId: 'goal_123',
    sessionId: window.__tpow_sid
  })
})

Server-side tracking: For higher reliability, fire the conversion from your backend after the action is confirmed (e.g., after a successful payment). Pass the session ID from your frontend to your backend, then make the API call server-side.

// Server-side conversion (Node.js example)
const response = await fetch(
  'https://api.tonicpow.com/v1/conversions',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TONICPOW_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      goalId: 'goal_123',
      sessionId: req.body.tpowSessionId,
      amount: 49.99 // optional: transaction value
    })
  }
)

Webhooks let your application receive real-time notifications when events occur on your campaigns. Configure webhook URLs in your dashboard under Settings > Webhooks.

When a click or conversion happens, TonicPow sends a POST request to your webhook URL with a JSON payload containing the event details:

// Webhook payload example
{
  "event": "conversion.completed",
  "campaignId": "camp_abc123",
  "goalId": "goal_123",
  "promoterId": "user_xyz",
  "amount": 0.005,
  "sessionId": "sess_456",
  "timestamp": "2025-01-15T10:30:00Z"
}

Your webhook endpoint should return a 200 status code within 10 seconds. Failed deliveries are retried up to 3 times with exponential backoff. Verify the webhook signature in the X-TonicPow-Signature header to confirm the request is authentic.

Use sandbox mode to test your integration without affecting production data or spending real funds. Generate a test API key from your dashboard. Test keys are prefixed with test_ and work against the sandbox environment.

The sandbox API lives at https://api.sandbox.tonicpow.com. All endpoints behave identically to production, but no real BSV is moved and no live campaigns are affected.

A typical test flow:

1. Create a test campaign via the API
2. Generate a promoter link for that campaign
3. Click the link in your browser to simulate a visit
4. Fire a test conversion using the session ID
5. Verify the conversion appears in your dashboard and webhook payload