Tracking Ingest API

The Tracking Ingest API lets you send conversion events from external systems — CRM webhooks, server-side applications, or third-party integrations — directly to SerpWise for forwarding to your configured ad platform integrations.

Endpoint

POST /tracking/ingest

Authentication

All requests must include an authentication header with your API key.

Authorization: Bearer your-api-key

Request Body

The request body is a JSON object with an events array. Each event object has the following fields:

userData Fields

customData Fields

Example Request

curl -X POST https://your-gateway.example.com/tracking/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "events": [
      {
        "platform": "meta",
        "eventType": "purchase",
        "userData": {
          "email": "customer@example.com",
          "phone": "+1234567890"
        },
        "customData": {
          "value": 99.99,
          "currency": "USD",
          "orderId": "ORD-12345",
          "contentIds": ["SKU-001", "SKU-002"]
        }
      },
      {
        "platform": "ga4",
        "eventType": "purchase",
        "userData": {
          "externalId": "user-789"
        },
        "customData": {
          "value": 99.99,
          "currency": "USD",
          "orderId": "ORD-12345"
        }
      }
    ]
  }'

PII Handling

PII fields in userData — email, phone, first name, and last name — are automatically hashed before being sent to ad platforms. You can send plain-text values; hashing is handled server-side.

If you send pre-hashed values, they will not be double-hashed.

Rate Limits

• Maximum 100 events per request
• Requests exceeding this limit will receive a 400 Bad Request response

Response

Success (200)

{
  "processed": 2,
  "errors": []
}

Partial Failure (207)

{
  "processed": 1,
  "errors": [
    {
      "index": 1,
      "message": "No active integration found for platform: snapchat"
    }
  ]
}

Error (400)

{
  "error": "Too many events. Maximum 100 per request."
}

Use Cases

• CRM webhooks — Fire a lead or purchase event when a deal closes in your CRM
• Server-side applications — Send conversion events from backend order processing systems
• Third-party integrations — Forward events from payment processors, form builders, or marketing automation tools
• Data pipelines — Replay historical conversion events through SerpWise for backfilling

Platform Rate Limits

SerpWise enforces per-platform rate limits to prevent hitting ad platform API quotas. Events are queued and sent within these limits automatically.

If your event volume exceeds these limits, the gateway queues events and sends them as capacity becomes available (up to 10 seconds max wait before proceeding). Events are never dropped due to rate limiting.

Auto-Enrichment

When a conversion event is triggered on a page that contains JSON-LD Product structured data or Open Graph product meta tags, SerpWise automatically populates missing value and currency fields from the page data.

This means you can configure a simple fire_conversion_event rule on /products/* pages without complex extraction rules — the gateway extracts pricing from your existing structured data.

Auto-enrichment only fills missing fields. Values explicitly set via extraction rules or the Ingest API are never overwritten. Product data is cached per URL with a 24-hour TTL.

Consent

Events sent via the Ingest API are subject to the same consent checks as gateway-generated events. If the target integration has consent requirements enabled, include consent signals in your request by setting the _sw_consent cookie value in a consent field:

{
  "platform": "meta",
  "eventType": "Purchase",
  "consent": {
    "granted": ["marketing"],
    "raw": "marketing"
  }
}

If consent is not included in the request and the integration requires it, the event will be logged with status consent_denied.