Segment Compatibility | Convertmax Docs

Convertmax accepts Segment-style event payloads on the event API and normalizes them into the Convertmax tracking schema before ingesting them.

Use this guide when you already send Segment track, identify, page, screen, group, or batch calls and want Convertmax to receive the same events with minimal changes.

Supported endpoints

Convertmax accepts Segment-compatible JSON on these endpoints:

POST /v1/track/
POST /v1/identify/
POST /v1/page/
POST /v1/screen/
POST /v1/group/
POST /v1/batch/

POST /v1/track/ can auto-detect a Segment payload from the request body. The other routes force the expected Segment event type.

Authentication

Use the same authentication options as the standard event API:

Authorization: Bearer <api_key>
?key=<api_key>

How Convertmax maps Segment events

Convertmax transforms Segment payloads into the internal event format using these rules:

Segment type	Convertmax `event_type`	Notes
`track`	mapped from `event`	Common names like `Purchase` map to `convert`; unknown names fall back to `custom`
`identify`	`custom`	Traits are preserved in `data.traits`
`page`	`page_view`	Page metadata is preserved in `data`
`screen`	`page_view`	Screen name is preserved in `data.screen_name`
`group`	`custom`	Group traits are preserved in `data.group_traits`
`batch`	per event item	Each item is normalized and ingested independently

Event name normalization for `track`

Convertmax maps common Segment event names like this:

Purchase, Order Completed, and checkout-style names become convert
Add To Cart and cart-style names become add_cart
page-style names become page_view
click-style names become click
search-style names become search
everything else becomes custom

Visitor and session mapping

Convertmax extracts identity values from the Segment payload like this:

visitor uses userId first, then anonymousId
session_id uses context.sessionId, context.session_id, or sessionId

Metadata preserved in `data`

The normalized Convertmax event keeps the original Segment context in data, including:

source: "segment"
segment_type
message_id
timestamp, sent_at, and original_timestamp
event_name
user_id, anonymous_id, and group_id
properties, traits, or group_traits when present
integrations
context
derived page fields such as page, page_title, page_path, and page_referrer

Track example

curl -X POST "https://event.convertmax.io/v1/track/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Purchase",
    "userId": "user_123",
    "anonymousId": "anon_123",
    "messageId": "msg_001",
    "context": {
      "sessionId": "sess_abc",
      "page": {
        "url": "https://example.com/checkout/success",
        "title": "Order complete"
      }
    },
    "properties": {
      "revenue": 100,
      "currency": "USD"
    }
  }'

This payload is normalized into a Convertmax event with:

event_type: "convert"
visitor: "user_123"
session_id: "sess_abc"
Segment metadata stored in data

Identify example

curl -X POST "https://event.convertmax.io/v1/identify/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "traits": {
      "email": "buyer@example.com",
      "plan": "pro"
    }
  }'

This is ingested as a Convertmax custom event with the original traits preserved in data.traits.

Page example

curl -X POST "https://event.convertmax.io/v1/page/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "anon_123",
    "name": "Pricing",
    "context": {
      "page": {
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "title": "Pricing"
      }
    }
  }'

This is ingested as a Convertmax page_view event.

Batch example

curl -X POST "https://event.convertmax.io/v1/batch/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batch",
    "userId": "user_123",
    "context": {
      "sessionId": "sess_abc"
    },
    "batch": [
      {
        "type": "page",
        "name": "Home",
        "context": {
          "page": {
            "url": "https://example.com/"
          }
        }
      },
      {
        "type": "track",
        "event": "Add To Cart",
        "properties": {
          "product_id": "sku_001",
          "quantity": 1
        }
      }
    ]
  }'

For batch requests, Convertmax applies the top-level userId, anonymousId, context, and integrations values to each item when those fields are missing on the individual event.