Flipsnack API reference: methods, parameters, examples

Overview

The Flipsnack API lets your own systems create, update, share and measure flipbooks, with nobody opening Flipsnack. For example, your system can publish a new catalog every night, or send reading statistics to your CRM. This page tells you what each method does, in plain English, and links to the developer documentation for the code.

💡 Benefits of using the Flipsnack API

• Publishing needs nobody at a keyboard: your system uploads a PDF and gets the flipbook's link back, so a nightly job can publish the new catalog.
• Price changes at scale: send up to 500 products per call, so a 10,000-SKU price change takes 20 calls.
• Access from your own tools: give or remove private access for teammates, one-time password readers or SSO groups.
• Reading data in your CRM: send views, time spent and clicks for a flipbook, or for one reader, to your own reports.

Every method at a glance

Click a method to go to its description.

The last 7 methods have their own articles. The product and catalog methods are in How to connect your product data to Flipsnack via API, which goes from the API key to a synced catalog.

Before your first call

Every request needs three things, whichever method you are calling:

• apiKey: issued for your account. In Flipsnack, open Settings, then Integrations, click Set up on Flipsnack API and click Generate API Keys. Getting started with the Flipsnack API covers requesting one.
• signature: an MD5 hash of the request, built as described in how to sign a request. An unsigned or wrongly signed call is rejected before anything else is checked.
• action: the method name from the list above, for example collection.getList.

Methods that work on one flipbook also need collectionHash, the flipbook's unique ID. The methods below list only the other parameters they need. The one exception is the Zapier sample method, which needs no signature.

Send requests to https://api.flipsnack.com/v1. The only exception is collection.create, which goes to https://upload.flipsnack.com/v1.

Responses are JSON and always carry a code and a status. Success is 20, not 200. Anything else leaves the reason in status, so check the code before reading the payload. The full list is in status codes below.

Rather than assembling one by hand, fill in the parameters below and copy a runnable request in cURL, Python, Node.js or PHP:

What each method does

Create a flipbook

Method: collection.create

Creates a new flipbook collection by uploading a source document from a local file or from a public URL. The method can also apply publishing status, basic metadata, Customize page settings, tracking settings, and uploaded customize assets such as logo, background image, and background audio.

Required parameters

• file: Local source file uploaded as multipart/form-data. Required if fileUrl is not provided.
• fileUrl: Public URL to the source file. Required if file is not provided.

Optional parameters

• collectionStatus: Publishing status. Possible values: public, editable (created as draft), unlisted, private (requires configuring private access settings via collection.setPermissions).
• logoImage: Logo image file (max 2 MB raster, 10 MB SVG). Raster logos are capped at 1000 × 1000 px.
• backgroundImage: Background image file (max 20 MB).
• backgroundAudio: Background audio file (max 20 MB, MP3/MPEG).
• layoutStyle: Recommended layout style override (smartView, singlePage, doublePage). Supersedes legacy singlePageView.
• background: Background type. Possible values: color, transparent, image. Default: color.

Response

Returns a JSON object with flipbook details, including title, description, thumbnail URL, status, and settings. Converting and publishing might take a few seconds, during that time the status of the flipbook will be “processing”. Use collection.getCollection to check the status of your flipbook.

Update a flipbook

Method: collection.update

Updates the settings of an existing flipbook. Because the flipbook will be republished, it might also take a few seconds before your changes go live. To confirm your updates are active, we recommend checking the flipbook’s status with collection.getCollection. Refer to the full documentation for a full list of parameters that can be modified.

Everything else is optional, and you send only what changes. The settings you can update are the same ones collection.create accepts: title and description, player size and controls, colors and skin, page transitions, logo and background, Google Analytics and Tag Manager ids, password, and collectionStatus to publish or unlist it. The reference lists all of them.

Response

Returns a JSON object with updated details, including title, description, thumbnail URL, status, and settings

Warning: This method is not available while the collection is in the processing state

Get a flipbook's details

Method: collection.getCollection

Gets the details of one flipbook, including its status. Use it to check when a new or updated flipbook is ready.

Response

Returns flipbook details, including title, description, thumbnail URL, status, and settings.

Delete a flipbook

Method: collection.deleteCollection

Moves a flipbook to the trash.

Response

Returns status code 20 - OK if successful.

Set who can read a private flipbook

Method: collection.setPermissions

This method configures and replaces the private access permissions configured for a flipbook. Note that permissions arrays can only hold objects of the same authorization type per unique request.

Required parameters

• permissions: JSON string with a permissions array. Replaces existing list. Must be URL-encoded.

Who you can give access to

• Teammates: a group of readers from your workspace. You send the group's name.
• One-time password readers: one reader by email address. Flipsnack emails them a code to open the flipbook.
• SSO readers: a group from your Single Sign-On setup. You send the group's name.

One request holds one kind of access only. To email an invitation to the people you add, turn on notifyViaEmail. To remove all private access, send an empty list. Each call replaces the whole list, so send everyone who should keep access.

The developer documentation shows the exact format and an example for each kind of access.

Response

Returns a JSON object containing the finalized, valid saved permissions array. Skipped or invalid workspace email addresses or groups are automatically pruned and returned as an empty array or omitted list.

See who can read a private flipbook

Method: collection.getPermissions

This method retrieves the currently configured private access permissions and visibility rules for a specific flipbook.

Response

Returns a JSON object containing the current visibility status and the private access permissions array active on the flipbook (e.g., teammates, OTP users, or SSO groups).

Get a flipbook's embed code

Method: collection.getEmbed

Gets the code that shows a flipbook on your website.

Optional parameters

• https: Deprecated. Default: true.
• responsive: If true, the embed will take the full container size. Default: false.
• startPage: Page number where the flipbook will open. Default: 1.
• width: Width of the embed.
• height: Height of the embed.

Response

Returns a JSON object with the embed code.

Get a flipbook's statistics

Method: collection.getStats

Gets the statistics of one flipbook, for your own reports.

Optional parameters

• startDate: Start date for the statistics interval (YYYY-MM-DD).
• endDate: End date for the statistics interval (YYYY-MM-DD).
• includePageStats: If true, returns statistics for each page.

Response

Returns a JSON object with statistics such as:

• impressions: Total player loads.
• views: User interactions with the player.
• time_spent: Total viewing time in seconds.
• downloads: Number of document downloads.
• api_uploads_left: Remaining uploads via API.

Get one reader's statistics

Method: collection.getReaderStats

Retrieves statistics for one identified reader of a flipbook: impressions, views, time spent, pages read, downloads and clicks. Use it for sales follow-ups or to update a contact in your CRM.

You identify the reader by email, one-time password email, SSO viewer ID, trackable link or link ID. You can also get the reader's activity on each page, the links they clicked and their reading sessions. Without dates, you get the last 30 days in UTC.

List your flipbooks

Method: collection.getList

Lists the flipbooks in your account, or in one folder.

Optional parameters

• collectionStatus: Type of collection, either public, editable or unlisted.
• query: Search query for titles and descriptions.
• from: Starting record index. Default: 0.
• to: Ending record index. Default: 50.
• orderBy: Field to order by (date_published, date_created, name). Default: date_published.
• orderMode: Order direction (asc, desc). Default: desc.
• folder: Folder path where collections are stored.

Response

Returns a JSON object with the total number of matching collections and a list of collections.

Download a flipbook as HTML5

Method: collection.downloadHTML

Generates and lets you download an HTML package for a flipbook. As this process might also take a few seconds or more, we recommend using the collection.getCollection method to retrieve the status of your publication.

Response

Returns a JSON object with the status of the request and a URL to download the HTML package once the generation is complete.

Process:

• Request HTML Package: Send the request with the necessary parameters.
• Check Status: The response will include a status code and, if successful, a URL to download the package.
• Download Package: Use the provided URL to download the HTML package.

Get your account's statistics

Method: user.getStats

Gets the totals for all flipbooks in your account.

Response

Returns a JSON object with statistics such as:

• impressions: Total player loads.
• views: User interactions with the player.
• time_spent: Total viewing time in seconds.
• downloads: Number of document downloads.
• api_uploads_left: Remaining uploads via API.

Get a sample lead form submission for Zapier

Method: zapier.getZapierLeadFormSample

Provides sample data from lead forms, for Zapier integration.

This method needs apiKey, action and collectionHash only, with no signature.

Response

Returns a JSON object with sample data, including fields such as "Email address", "Full name", "Phone number", and more.

Limits to plan for

An integration meets these limits in normal use, so plan retries and batches from the start.

• Rate: 5 calls per second and 60 per minute per API key, reads included. Over either and the call returns 31 or 32.
• Uploads: 1,000 successful collection.create calls a month on Enterprise; your workspace's flipbook limit still applies on top. Over it returns 33.
• Files: one PDF or JPG per call, up to 500 MB. Merge multiple PDFs before uploading, because a second file returns 36.
• Products: products.create, products.update and products.delete take up to 500 products per call, so a 10,000-SKU price change is 20 calls.
• Customization assets: logo 2 MB raster or 10 MB SVG and no larger than 1000 × 1000 px, background image 20 MB, background audio MP3 up to 20 MB. The type is detected server-side, so the extension has to match the actual file.
• Processing: a new flipbook is not ready the moment the call returns. Poll collection.getCollection until its status stops being processing, rather than assuming a fixed wait.

Status codes

Every response carries one. These are the ones worth handling explicitly:

• 20: OK. The call worked; anything it returns is in data.
• 22: Maintenance mode. Retry later.
• 30: Missing mandatory parameter, named in the response.
• 31 / 32: Per-second or per-minute rate limit. Back off and retry.
• 33: Monthly upload cap reached.
• 34: File too large, or a raster logo over 1000 × 1000 px.
• 35: Too many pages in the document.
• 36: More than one file in a single create call.
• 38: The flipbook is still processing. Poll rather than retrying the create.
• 40: Bad request: a POST on a non-upload call, a GET on an upload call, or a malformed URL.
• 41: Invalid API key. 44: Invalid signature; regenerate it rather than reusing one.
• 42: Unknown action. 43: The flipbook is deleted or belongs to another account. 46: No such flipbook.
• 50: Server error. Retry, and contact support if it persists.

The complete list lives at API status codes.

Get reader activity sent to your system (webhooks)

With the methods above, your system asks Flipsnack for data. A webhook works the other way: when a reader does something in a flipbook, Flipsnack sends the details at once to a web address that you choose. Your system does not have to keep asking for new data.

Flipsnack sends a webhook for 3 kinds of reader activity:

• Orders: a reader places a Shopping list order.
• Contact forms: a reader submits a form in a flipbook.
• Cart events: a reader adds, removes or changes an item in the cart. Use these for abandoned-cart emails or live stock checks.

Additional tips / FAQs

• Which plan includes API access? It is granted on request as part of Enterprise. Ask your account manager, or talk to sales.
• Why is my call rejected before it does anything? Almost always the signature. It is an MD5 of the request built exactly as how to sign a request describes, so regenerate it rather than reusing one from an earlier call.
• Can I create a flipbook without hosting the file myself? Yes. collection.create takes either a file as multipart/form-data or a fileUrl that Flipsnack fetches.
• How do I get numbers out? collection.getStats for one flipbook, collection.getReaderStats for one reader, user.getStats for the account.
• Do I need the API to connect Flipsnack to other tools? Often not. Zapier covers most integrations without code.
• Where is the full developer documentation? At developers.flipsnack.com, which is the source of truth for payloads and error codes; this page is the guided version.

Next steps

• Flipsnack API documentation
• Webhooks for orders
• Getting started with the Flipsnack API

Need expert support?

Our team is here to help. Connect with our experts or message us via the live chat for personalized assistance.