---
title: "Tracking Ingest API - Serpwise Documentation"
description: "Send server-to-server conversion events into the Serpwise gateway for platform forwarding."
url: "https://serpwise.ai/docs/tracking-api/"
source: "https://serpwise.ai/docs/tracking-api/"
---
[Back to Serpwise](/)

Serpwise Documentation

Connect · Configure · Execute

Search documentation

`/`

No documentation found.

↑↓ Navigate Enter to open

Browse documentation

The Tracking Ingest API accepts conversion events from trusted server systems and queues them for the same forwarding pipeline used by gateway-generated conversions.

Use it for CRM webhooks, order processors, backend checkout systems, data pipelines, or any server that can send events directly to the Serpwise gateway.

## Endpoint

```
POST /tracking/ingest
```

## Authentication

```
X-Internal-Key: your-internal-gateway-key
```

Requests without a matching key return `401 Unauthorized`.

## Limits

| Limit                      | Value              |
|----------------------------|--------------------|
| Maximum body size          | 1 MB               |
| Maximum events per request | 100                |
| Method                     | `POST` only        |
| Content type               | `application/json` |

## Request Body

```
type TrackingIngestRequest = {
	domainId: string;
	events: TrackingIngestEvent[];
};

type TrackingIngestEvent = {
	platform:
		| "meta"
		| "tiktok"
		| "google_ads"
		| "webhook"
		| "google_analytics"
		| "snapchat"
		| "pinterest"
		| "twitter";
	eventName: string;
	eventValue?: number;
	eventCurrency?: string;
	userData?: {
		email?: string;
		phone?: string;
		clientIp?: string;
		userAgent?: string;
	};
	customData?: {
		order_id?: string;
		orderId?: string;
		content_ids?: string[];
		contentIds?: string[];
		num_items?: number;
		numItems?: number;
		[key: string]: unknown;
	};
};
```

### Top-Level Fields

| Field      | Required | Description                                         |
|------------|----------|-----------------------------------------------------|
| `domainId` | Yes      | Domain UUID that owns the destination integrations. |
| `events`   | Yes      | Array of 1-100 events.                              |

### Event Fields

| Field           | Required | Description                                                                                     |
|-----------------|----------|-------------------------------------------------------------------------------------------------|
| `platform`      | Yes      | Destination platform. Must match a supported gateway conversion platform.                       |
| `eventName`     | Yes      | Platform event name, such as `Purchase`, `Lead`, `AddToCart`, or a custom webhook event.        |
| `eventValue`    | No       | Numeric conversion value. Stored and forwarded as a two-decimal string.                         |
| `eventCurrency` | No       | Currency code such as `USD`, `EUR`, or `DKK`.                                                   |
| `userData`      | No       | Identity and browser context. Email and phone are hashed before forwarding.                     |
| `customData`    | No       | Event-specific fields. Supported normalized keys include order ID, content IDs, and item count. |

## Example

```
curl -X POST https://gateway.example.com/tracking/ingest \
  -H "Content-Type: application/json" \
  -H "X-Internal-Key: $SERPWISE_INTERNAL_KEY" \
  -d '{
    "domainId": "29aea826-aec4-41ba-917e-e6aa1fefbb03",
    "events": [
      {
        "platform": "meta",
        "eventName": "Purchase",
        "eventValue": 189.00,
        "eventCurrency": "USD",
        "userData": {
          "email": "customer@example.com",
          "phone": "+15551234567",
          "clientIp": "203.0.113.10",
          "userAgent": "Mozilla/5.0 ..."
        },
        "customData": {
          "order_id": "ORD-12345",
          "content_ids": ["SKU-001", "SKU-002"],
          "num_items": 2
        }
      }
    ]
  }'
```

## Response

The endpoint returns `200 OK` when the request is accepted, even if individual events have validation or integration lookup errors.

```
{
	"accepted": 1,
	"errors": []
}
```

Partial success example:

```
{
	"accepted": 1,
	"errors": ["event[1]: integration not found for platform \"snapchat\""]
}
```

## Error Responses

| Status | Cause                                                                      |
|--------|----------------------------------------------------------------------------|
| `405`  | Method is not `POST`.                                                      |
| `401`  | Missing or invalid `X-Internal-Key`.                                       |
| `503`  | Conversion forwarding is not enabled on the gateway.                       |
| `413`  | Body exceeds 1 MB.                                                         |
| `400`  | Invalid JSON, missing `domainId`, empty `events`, or more than 100 events. |

## PII Handling

The gateway hashes email and phone values before forwarding them to ad platforms. Raw email and phone values from the ingest payload are not sent directly.

`clientIp` must parse as an IP address or it is dropped. `userAgent` is forwarded as non-PII browser context.

## Delivery Semantics

For each valid event, the gateway:

1. Validates the platform.
2. Builds a conversion event with a new event ID.
3. Hashes PII fields.
4. Looks up the active integration for the domain and platform.
5. Queues the event for asynchronous forwarding.
6. Records delivery status in the Event Log.

If the queue is full, that event is rejected in the response `errors` array.

## Related Docs

[**Tracking Overview**  
→  
\
Understand how gateway-generated and ingested events move through the pipeline.](/docs/conversion-tracking)

[**Tracking Events**  
→  
\
Create dashboard-managed conversions and configure extraction.](/docs/tracking-events)

[**Tracking Integrations**  
→  
\
Add destination credentials before sending ingest events.](/docs/tracking-integrations)