Analytics API

Track viewer engagement and retrieve analytics data including page views, unique viewers, read time, geographic breakdown, and device statistics.

On this page

Track an Event
Request Body
Example Request
Example Response
Organization Overview
Query Parameters
Example Request
Example Response
Publication Analytics
Query Parameters
Example Request
Example Response
Response Fields
Export Analytics as CSV
Query Parameters
Example Request
Example Response
Event Types Reference

Analytics API

The Analytics API lets you track viewer interactions with your publications and retrieve engagement metrics. Analytics data includes page views, unique viewers, read time, page-level heatmaps, geographic distribution, and device breakdowns.

Base URL: https://api.zenflip.io/v1/analytics

Track an Event

Record a viewer interaction event. This is a public endpoint used by the embedded flipbook viewer --- no authentication is required.

Rate limit: 30 events per second per IP address (to accommodate rapid page turns).

Request Body

Field	Type	Required	Description
`publicationId`	string	Yes	UUID of the publication being viewed
`eventType`	string	Yes	Event type (max 30 chars): `page_view`, `session_start`, `session_end`, `download`, `share`
`sessionId`	string	No	Viewer session identifier (max 100 chars)
`viewerId`	string	No	Anonymous viewer identifier (max 100 chars)
`pageNumber`	integer	No	Page number that was viewed
`duration`	integer	No	Time spent on the page in seconds
`deviceType`	string	No	Device category: `desktop`, `tablet`, `mobile`
`browser`	string	No	Browser name (e.g., `Chrome`, `Safari`)
`os`	string	No	Operating system (e.g., `macOS`, `Windows`, `iOS`)
`country`	string	No	ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`)
`city`	string	No	City name (max 100 chars)
`referrer`	string	No	Referrer URL (max 500 chars)
`metadata`	object	No	Arbitrary key-value metadata

Example Request

Example Response

Organization Overview

Retrieve a high-level analytics summary across all publications in your organization.

Query Parameters

Parameter	Type	Required	Description
`start`	string	No	Start date in ISO 8601 format (e.g., `2026-01-01T00:00:00Z`)
`end`	string	No	End date in ISO 8601 format
`range`	string	No	Shorthand range: `7d`, `30d`, `90d` (overridden by start/end)

Example Request

Example Response

Publication Analytics

Retrieve detailed analytics for a specific publication, including page-level heatmap data, geographic distribution, and device breakdown.

Query Parameters

Parameter	Type	Required	Description
`start`	string	No	Start date (ISO 8601)
`end`	string	No	End date (ISO 8601)

Example Request

Example Response

Response Fields

Field	Description
`summary`	Aggregate metrics for the date range
`pageHeatmap`	Per-page view counts and average time spent
`geography`	Viewer distribution by country (ISO alpha-2 codes)
`devices`	Breakdown by device type (desktop, mobile, tablet)
`browsers`	Breakdown by browser name
`viewsByDay`	Daily time series of views and unique viewers

Export Analytics as CSV

Export raw analytics data as a CSV file for use in spreadsheets or business intelligence tools.

Required plan: Creator or above.

Query Parameters

Parameter	Type	Required	Description
`pubId`	string	No	Filter by publication ID
`start`	string	No	Start date (ISO 8601)
`end`	string	No	End date (ISO 8601)

Example Request

Example Response

The CSV string is returned in the data field. Parse it on the client side or save directly to a file.

Event Types Reference

Event Type	Description
`session_start`	Viewer opened the publication
`page_view`	Viewer navigated to a specific page
`session_end`	Viewer closed the publication or navigated away
`download`	Viewer downloaded the PDF (if enabled)
`share`	Viewer used the share functionality

← Previous

Publications API

Lead Capture API