Tracking

Tracking endpoints sit under /api/brands/{brand}/ with moduleAccess:tracking middleware. Authenticate with EF-Access-Key.

Clicks

The Clicks API exposes click tracking data from visitor sessions. Clicks are stored in Elasticsearch (or ClickHouse when enabled for the account).

List Clicks

GET /api/brands/{brand}/clicks

Page size is fixed at 30 for the clicks index and cannot be changed via per_page.

page

number

Page number (default: 1)

query

string

Filter by URL (partial match)

subid

string

Filter by Sub ID 1 (sub tracking parameter)

subid2

string

Filter by Sub ID 2

subid3

string

Filter by Sub ID 3

subid4

string

Filter by Sub ID 4

vtid

string

Filter by visit tracking ID

click_id

string

Filter by specific click/session ID — collapses results to unique sessions

ip_address

string

Filter by IP address

pgid

number

Filter by page ID

funnel_id

number

Filter by funnel ID

merchant_id

number

Filter by merchant ID

exclude_bots

boolean

Exclude bot traffic from results

start

string

Date range start (ISO 8601). Used by DateRangeService.

sortBy

string

Column to sort by (limited to sortable fields)

sortDir

string

Sort direction: asc or desc

cURL

curl "https://app.elasticfunnels.io/api/brands/{brand_id}/clicks?funnel_id=5&page=1" \
  -H "EF-Access-Key: your_api_key_here"

{
  "total": 1240,
  "last_page": 42,
  "current_page": 1,
  "per_page": 30,
  "next_page_url": true,
  "data": [
    {
      "id": "click-es-doc-abc",
      "session_id": "sess-xyz-123",
      "ip_address": "203.0.113.50",
      "url": "/checkout",
      "funnel_id": 5,
      "domain": { "id": 7, "domain": "checkout.mybrand.com" },
      "affiliate": null,
      "merchant": { "id": 1, "merchant": "NMI" },
      "events": [ /* event objects */ ],
      "created_at": "2024-12-10T09:00:00Z"
    }
  ]
}

Get Click Details

GET /api/brands/{brand}/clicks/{click_code}

click_code

string

required

Session ID or click code

{
  "id": "click-es-doc-abc",
  "session_id": "sess-xyz-123",
  "ip_address": "203.0.113.50",
  "url": "/checkout",
  "funnel_id": 5,
  "domain": { /* domain */ },
  "events": [ /* events */ ]
}

{ "message": "Not found" }

Get Session Details

Returns geo data and the full sequence of events for a visitor session.

GET /api/brands/{brand}/clicks/session/{sessionId}

sessionId

string

required

Session ID

cURL

curl https://app.elasticfunnels.io/api/brands/{brand_id}/clicks/session/sess-xyz-123 \
  -H "EF-Access-Key: your_api_key_here"

{
  "geoData": {
    "lat": 34.052,
    "lon": -118.244,
    "city": "Los Angeles",
    "region": "CA",
    "country": "US",
    "zip": "90001",
    "ip_address": "203.0.113.50"
  },
  "events": [
    {
      "type": "page_view",
      "url": "/checkout",
      "timestamp": "2024-12-10T09:00:00Z",
      "data": {}
    },
    {
      "type": "add_to_cart",
      "timestamp": "2024-12-10T09:01:30Z",
      "data": { "product_id": 3 }
    }
  ],
  "domains": {
    "7": "https://checkout.mybrand.com"
  }
}

{
  "geoData": [],
  "events": []
}

Export Clicks

Queue a CSV export of click records.

POST /api/brands/{brand}/clicks/export

filters

array

Filter conditions (same as list query params)

selected_codes

array

Limit export to specific click codes

columns

array

Columns to include in the export

cURL

curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/clicks/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"columns": ["session_id", "ip_address", "url", "created_at"]}'

{
  "success": true,
  "message": "Export started. You will receive an email when it is ready."
}

Session Replays

Session replays capture mouse movements, clicks, and scroll events for visitor sessions.

List Session Replays

GET /api/brands/{brand}/replays

session_id

string

required

Session ID to retrieve replays for

[
  {
    "id": "replay-doc-abc",
    "session_id": "sess-xyz-123",
    "page_session_id": "page-sess-456"
  }
]

Get Session Replay

Retrieve the full recorded event stream for a session.

GET /api/brands/{brand}/replays/{sessionId}

sessionId

string

required

Session replay document ID (from the list endpoint)

cURL

curl https://app.elasticfunnels.io/api/brands/{brand_id}/replays/replay-doc-abc \
  -H "EF-Access-Key: your_api_key_here"

{
  "id": "replay-doc-abc",
  "session_id": "sess-xyz-123",
  "page_session_id": "page-sess-456",
  "url": "/checkout",
  "duration_ms": 45000,
  "viewport_width": 1440,
  "viewport_height": 900,
  "events": [
    { "type": "mousemove", "x": 100, "y": 200, "ts": 1500 },
    { "type": "click", "x": 300, "y": 400, "ts": 2300, "target": "button#buy-now" },
    { "type": "scroll", "scrollY": 800, "ts": 5000 }
  ]
}

If the session replay document does not exist in Elasticsearch, the response may produce an error. Always use session_id values returned from the list endpoint.

Short Links

Short links create trackable redirects for marketing campaigns, affiliate links, and social sharing.

Generate Short Link

POST /api/brands/{brand}/short-links/generate

destination_url

string

required

The destination URL the short link will redirect to. Must be a valid URL.

cURL

curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/short-links/generate \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://checkout.mybrand.com/offer?utm_source=email"}'

Python

import requests

response = requests.post(
    f'https://app.elasticfunnels.io/api/brands/{brand_id}/short-links/generate',
    headers={'EF-Access-Key': 'your_api_key_here'},
    json={'destination_url': 'https://checkout.mybrand.com/offer?utm_source=email'}
)
data = response.json()
print(f"Short URL: {data['url']}")  # https://go.mybrand.com/g/abc123

{
  "code": "abc123",
  "url": "https://go.mybrand.com/g/abc123"
}

{
  "errors": {
    "destination_url": ["Invalid URL"]
  }
}

Notes

Click data is stored in Elasticsearch by default, but accounts with ClickHouse enabled use a separate engine — both are queried transparently via the same API
The session replay events array is stored as a compressed/encoded string in Elasticsearch and decoded automatically before being returned
Short links are served from the SHORT_URL_DOMAIN configured for your account (e.g. go.yourdomain.com)
The clicks index endpoint always returns 30 results per page regardless of per_page parameter

Getting Started

Endpoints

Clicks

List Clicks

Get Click Details

Get Session Details

Export Clicks

Session Replays

List Session Replays

Get Session Replay

Short Links

Generate Short Link

Notes

​Clicks

​List Clicks

​Get Click Details

​Get Session Details

​Export Clicks

​Session Replays

​List Session Replays

​Get Session Replay

​Short Links

​Generate Short Link

​Notes

Clicks

List Clicks

Get Click Details

Get Session Details

Export Clicks

Session Replays

List Session Replays

Get Session Replay

Short Links

Generate Short Link

Notes