Guide

Upload a PDF and track who reads it

Convert a document into a flipbook, wait for the background job to finish, then find out who opened it, which pages held their attention and where they dropped off.

Before you start

An API key with the books:read, books:write and analytics:read scopes.
A document to upload — PDF, Word, Excel, PowerPoint, JPG or PNG.
Per-reader analytics (steps 4 and 5) are available on the Company plan.

1
Upload the document
Send the file as multipart/form-data under files[]. Upload one file per request.
Conversion is queued rather than immediate, so a successful call returns 202 Accepted and a batch_id — not a finished flipbook.
POST /books
```
curl -X POST https://app.flipbooker.com/api/v1/books \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[][email protected]" \
  -F "status=draft"
```
Send an Idempotency-Key
If the connection drops you will not know whether the upload landed. Retrying with the same Idempotency-Key returns the original response instead of creating a second flipbook.

Poll the batch until conversion finishes

Use the batch_id from step 1. The batch reports a progress breakdown and, as pages are rendered, the books it produced.

Poll every few seconds rather than in a tight loop — the per-endpoint rate limit is 100 requests per minute.

GET /batches/{batchId}

curl https://app.flipbooker.com/api/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY"

Response

{
  "data": {
    "id": "9f1c2e7a-...",
    "status": "completed",
    "progress": { "total": "1", "completed": "1", "pending": "0", "failed": "0" },
    "books": [
      {
        "id": 4821,
        "name": "quarterly-report",
        "status": "draft",
        "page_count": 24,
        "preview_url": "https://flipbooker.com/books/..."
      }
    ]
  }
}

Publish the flipbook

A draft is not publicly reachable. Flip it to publish once you are happy with it, using the book id from the batch.

PUT /books/{id}

curl -X PUT https://app.flipbooker.com/api/v1/books/4821 \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"publish"}'

4
See who has been reading
Ask for one row per reader, sorted by engagement rather than recency. book_id is required; everything else is optional filtering.
The response is cursor-paginated, so follow meta.next_cursor for workspaces with a lot of traffic.
GET /analytics/readers
```
curl -G https://app.flipbooker.com/api/v1/analytics/readers \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -d book_id=4821 \
  -d sort=engagement \
  -d limit=50
```
Anonymous readers
By default only identified readers are returned. Pass include_anonymous=true to include people who never gave an email address.
5
Find the pages that lose people
Reader-level data tells you who; page-performance tells you where. It aggregates dwell time and interactions per page across every reader of a flipbook.
To follow a single reader end to end instead, call GET /analytics/reader-journey with their viewer_id.
GET /analytics/page-performance
```
curl -G https://app.flipbooker.com/api/v1/analytics/page-performance \
  -H "Authorization: Bearer $FLIPBOOKER_API_KEY" \
  -d book_id=4821
```

Where to next

API reference Get these events pushed to you Sync leads to your CRM

Before you start

Upload the document

Poll the batch until conversion finishes

Publish the flipbook

See who has been reading

Find the pages that lose people

Where to next