Quickstart

This guide walks you through your first Ingest API calls. You'll need a source API key — see Authentication if you haven't created one yet.

All examples use curl. Replace YOUR_API_KEY with your actual key, and include at least one of userId, externalId, or email to identify the visitor.

Prefer an SDK? See SDKs — the Ingest API is wrapped for Node.js, Python, Go, Ruby, PHP, C#, and Kotlin. Everything below maps one-to-one to an SDK method.

Track an Event

Send a single event with POST /track:

curl -X POST https://api.oursprivacy.com/api/v1/track \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase",
    "userId": "user123",
    "token": "YOUR_API_KEY",
    "properties": {
      "amount": 99.99,
      "product": "Premium Plan"
    }
  }'

Identify a Visitor

Set or update visitor properties without firing an event with POST /identify:

curl -X POST https://api.oursprivacy.com/api/v1/identify \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "token": "YOUR_API_KEY",
    "userProperties": {
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "plan": "premium"
    }
  }'

To both identify a visitor and record an event in one call, use /track and include the visitor properties there.

Backfill a Past Event

Set the time field (milliseconds since the UTC epoch) to record an event with its original timestamp. Events can be backfilled up to 7 days in the past.

curl -X POST https://api.oursprivacy.com/api/v1/track \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase",
    "userId": "user123",
    "token": "YOUR_API_KEY",
    "time": 1754874909594
  }'

Backfilled events appear in Recent Events ordered by their time value, not when they were sent.

Send Many Events at Once

For replay, backfill, or high-volume sends, POST /batch accepts one top-level token plus an events[] array of /track-shaped rows. Review the response results array row by row and retry only the rows that failed. See the Batch Events reference for the full response contract.

Verify in the Dashboard

Confirm events are arriving in Recent Events. Use your Test Mode key first to validate the integration without dispatching to destinations.

Error Handling

OpenAPI Specification

The full OpenAPI spec is available at:

GET https://api.oursprivacy.com/api/v1/openapi

Use it to generate clients, explore the schema, or import into tools like Postman. See OpenAPI Schema for the rendered reference.

Next Steps

• Authentication — source keys, Test Mode, and rotation.
• SDKs — language wrappers around this API.
• Track Events reference — the full request and response schema.