Ingest API Integration

The Ours Privacy Ingest API allows you to track events directly from your backend systems. This is particularly useful for situations where the Web SDK cannot be used, such as server-side applications, CRMs, or other backend-only workflows.

Why Use Ingest API Tracking?

Ingest API tracking enables you to:

• Capture Offline or Backend Events:
  • Track interactions and events that occur outside of the client-side, such as form submissions, database updates, or external system interactions.
• Ensure Data Completeness:
  • Maintain data accuracy even when users have disabled JavaScript or blocked tracking scripts.
• Enhance Privacy Compliance:
  • Collect and process data securely without client-side exposure.

Ingest API Endpoints

The Ours Privacy Ingest API provides two main endpoints for different purposes:

Track Events Endpoint (/api/v1/track)

Use this endpoint to track specific events that occur in your system. This is the primary method for capturing user actions and behaviors.

When to use:

• Tracking user actions (purchases, form submissions, page views, etc.)
• Capturing business events (conversions, sign-ups, etc.)
• Sending event data to configured destinations

Example:

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 Visitors Endpoint (/api/v1/identify)

Use this endpoint to define or update visitor properties without firing an event. This is useful for setting user attributes that will be associated with future events.

When to use:

• Setting user properties (name, email, plan type, etc.)
• Updating user profile information
• Creating user profiles before tracking events

Important: This endpoint does not fire an event. If you want to both identify a user and track an event, use the track endpoint and include user properties in the request.

Example:

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"
    }
  }'

For detailed API specifications, refer to the Track Events API reference and Identify Visitors API reference.

Getting Started with the Ingest API

1. Add the Ingest API Source

You first need to add the Ingest API source to your account:

1. Go to Sources > Add source
2. Select the Ingest API source
3. You'll receive an API key and example CURL commands for both endpoints

2. Choose Your User Identification Method

When sending data to either endpoint, you must include one of these identifiers to associate the data with a user:

• userId: The visitor ID stored in local storage and cookies on your web properties
• externalId: Your unique custom identifier you want to group this and other visitors together by.
• email: The email address you either associated with the visitor during a Web session or want to associate with the visitor.

Best Practice: Use the same identifier across your web and server implementations to ensure proper user association.

3. Start with Simple Examples

Try the basic examples from the Ingest API Endpoints section above. You can test these in the Track Events API reference before implementing in your code.

Backfilling Events

You can backfill historical events that occurred in the past using the Ingest API. This is useful for importing data from existing systems or correcting missing events.

Event Age Limits

• Maximum Age: You can send events up to one year old
• Time Format: The time field must be in milliseconds since UTC epoch

Using the time Field

The time field specifies when the event occurred:

• If empty: Assumes the current time (now)
• If set: Must be in milliseconds since UTC epoch

Example

Backfilled event (24 hours ago):

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
  }'

You can test these examples in the Track Events API reference.

Viewing Backfilled Events

Use Query Events to find backfilled events by their original date. To inspect a test request as it arrives, use the REST API example in Recent Events.

Test Mode in Ingest API Integration

When using the Ingest API, you have the option to test your integration with a Test Mode API Key. Test Mode allows you to debug and validate your setup without dispatching events to configured destinations.

Setting Up Test Mode

1. Retrieve a Test API Key:

   • Navigate to the Install page in your dashboard.
   • Copy the Test Mode API Key.

2. Use the Test API Key in API Requests:

   • Include the Test API Key in your API requests as part of the headers or body.

Check Your Test Request

In Recent Events, select Send debug events, then REST API. Use the example with your test key and send the request. Select the event marked Test to inspect its properties and destination mappings. Test events are not delivered to destinations.

Replace the test key with your live key when you are ready to send real events.

API Key Rotation

For enhanced security, we recommend regularly rotating your API keys. Here's how to safely rotate your Ingest API keys:

1. Create a New Source:

   • Go to Sources > Add source and create a new Ingest API source
   • This will generate a new API key while keeping your existing one active

2. Update Your Integration:

   • Update your backend systems to use the new API key
   • Continue sending events to both sources during the transition period

3. Monitor Event Flow:

   • Use the Recent Events Dashboard to verify that events are being received by the new source
   • Check that the event volume matches your expectations

4. Complete the Rotation:

   • Once you confirm that all events are flowing to the new source, you can safely deactivate and delete the old source
   • This phased approach ensures no events are lost during the rotation process

Debugging and Troubleshooting

If you encounter issues with the Ingest API:

1. Check the API Response:

   • The API returns clear error messages and status codes. Common issues include:
     • 401 Unauthorized: Check your API key.
     • 400 Bad Request: Verify required fields and JSON structure.

2. Verify Events in the Dashboard:

   • Use the Recent Events Dashboard to see if your events are being ingested and processed.

3. Contact Support:

   • If you're unable to resolve an issue, reach out to support@oursprivacy.com for assistance.

Use Cases for Ingest API Tracking

CRM or Backend Workflows

Track events such as:

• User status changes (e.g., LeadConverted).
• Data imports from external systems.

Offline Conversions

Capture offline interactions like:

• In-person purchases.
• Call center activity.

Secure Event Processing

Send sensitive data (e.g., medical or financial) directly from a secure backend environment.