Migrate events from v3 to v5

This guide outlines the key changes when migrating your integration from the v3 event endpoints (/v3/events/{eventID} and /v3/events) to the current v5 events endpoint (/v5/events).

Overview of Changes

The v5 endpoint (/v5/events) offers a unified and more flexible way to send both recommended and custom events to Omnisend.

Key Differences:

Feature	v3 (`/events/{eventID}`)	v3 (`/events`)	v5 (`/events`)
Endpoint URL	`POST /v3/events/{eventID}`	`POST /v3/events`	`POST /v5/events`
Purpose	Trigger specific predefined event by ID	Trigger/Create custom event by `systemName`	Send any customer event (recommended or custom)
Event ID	Path parameter (`eventID`)	N/A	Optional body parameter (`eventID` UUID for deduplication)
Event Name	Implicit (defined by `eventID`)	Body parameters (`name`, `systemName`)	Required body parameter (`eventName`)
Contact Info	Body parameters (`email`, `phone`)	Body parameters (`email`, `phone`)	Body parameter (`contact` object containing identifiers like email, phone, etc.)
Custom Fields	Body parameter (`fields` object)	Body parameter (`fields` object)	Body parameter (`properties` object - recommended structure varies by event)
Event Version	N/A	N/A	Optional body parameter (`eventVersion` - check docs for recommended events, empty for custom events)
Event Time	Implicit (processing time)	Implicit (processing time)	Optional body parameter (`eventTime` RFC3339 - defaults to now) also used for deduplication.
Origin	N/A	N/A	Required body parameter (`origin` - "api" or specific app integration name)
Deduplication	Not specified	Not specified	Supported via eventID and eventTime properties. If an event with the same eventID and eventTime is sent multiple times, we will process it only once. Works only for historical events. Not working on real-time events used for automations.
Flexibility	Limited to predefined events	Limited to custom events	Handles both recommended and custom events; richer data structure

Migration Steps

Update Endpoint URL: Change all API calls targeting /v3/events/* to point to /v5/events.
Modify Request Body Structure: The request body needs significant changes:
- Combine Contact Info: Instead of top-level email or phone, structure contact identifiers within a contact object. Refer to the v5 documentation for the full contact object structure.
- Use eventName: Replace eventID (path parameter) or systemName (body parameter) with the eventName body parameter. Check the Omnisend event documentation for the correct eventName strings for predefined events. For custom events, use your desired name here.
- Use properties: Move custom fields from the fields object to the properties object. Consult the v5 events documentation for recommended properties for specific predefined events to ensure full feature compatibility.
- Add origin: Include the origin field (e.g., "origin": "api").
- Optional fields: Consider adding eventID (UUID v4), eventTime (RFC3339), and eventVersion where applicable.
Update Authentication: Ensure you are using the correct API key and authentication method (X-API-KEY header) compatible with the v5 API. (While not detailed in the browsed snippets, this is a standard consideration).
Review Event Documentation: Familiarize yourself with the specific eventName, eventVersion, and recommended properties for the events you are sending by consulting the Omnisend v5 event documentation.

Example Comparison (Conceptual)

v3 Trigger Custom Event (/v3/events)

// POST /v3/events
// Headers:
    Content-Type: application/json
    X-API-KEY: YOUR_API_KEY
{
  "name": "custom purchase event",
  "systemName": "custom_purchase_event",
  "email": "[email protected]",
  "fields": {
    "orderTotal": 123.45,
    "currency": "USD"
  }
}

IMPORTANT
Pass the compatibility: no-origin header to ensure that your segmentation and automation rules will continue to operate properly.

// POST /v5/events
// Headers:
    Content-Type: application/json
    X-API-KEY: YOUR_API_KEY
    compatibility: no-origin
{
  "eventName": "custom purchase event", // Use eventName instead of systemName
  "eventTime": "2025-04-18T11:53:40Z", // Optional: Time of event
  "origin": "api",                     // Required origin
  "contact": {                         // Structured contact info
    "email": "[email protected]"
  },
  "properties": {                      // Custom fields go in properties
    "orderTotal": 123.45,
    "currency": "USD"
  }
  // "eventID": "your-unique-event-uuid-v4" // Optional: for deduplication (eventTime also needed)
  // "eventVersion": "" // Optional for custom events
}