Skip to content
  • There are no suggestions because the search field is empty.

Flipsnack API reference: methods, parameters, examples

Every API method with the parameters it takes and what it returns

💡 Benefits of using the Flipsnack API
  • Publishing needs nobody at a keyboard: collection.create posts a PDF or JPG of up to 500 MB and returns the flipbook's link, so a nightly job publishes the catalog.
  • 500 products per call: product.create, update and delete each take that many, so a 10,000-SKU price change is 20 calls.
  • 5 calls a second, 60 a minute, 1,000 uploads a month: per key on Enterprise. Over the per-second or per-minute rate the call returns error code 31 or 32.
  • user.getStats and collection.getStats: views and reads per flipbook, so engagement reaches your own reporting.

Overview

The Flipsnack API (Application Programming Interface) enables businesses and developers to integrate Flipsnack seamlessly into their existing workflows. With this API, users can automate flipbook creation, update collections, access analytics, and dynamically embed content, streamlining content management and enhancing efficiency.

Requirements

  • Plan: API access is available on demand as part of the Enterprise plan.
  • Target audience: Developers, IT professionals, automation engineers, and business teams looking to integrate Flipsnack into their existing workflows.

Every method at a glance

Requests are told apart by the action parameter. Everything goes to https://api.flipsnack.com/v1 except collection.create, which posts to https://upload.flipsnack.com/v1. Jump straight to the method you need:

Method
What it does
Create a flipbook from a file or a URL
Change an existing flipbook and its settings
Read one flipbook and its metadata
Move a flipbook to trash
Set who may open a private flipbook
Read the current reader permissions
Get the embed code for a flipbook
Read views, time spent and engagement
List the flipbooks in a workspace
Download the HTML5 package
Read account-level statistics
Sample lead-form payload for Zapier
Add products to a feed
Change products already in a feed
Remove products from a feed
Build a catalog from a product feed
Generate a flipbook from a template
Email a published flipbook to a list
Re-sync a catalog after its feed changes

The three catalog methods are documented in how to connect your product data to Flipsnack via API, which walks the catalog flow from 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. 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.

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:

Request and response parameters

The Flipsnack API uses RESTful requests and returns JSON responses.

API 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, player settings, tracking settings, and uploaded customize assets such as logo, background image, and background audio.

Required Parameters

  • apiKey: Your Flipsnack API key.
  • signature: MD5 hash signature. For more details on creating a signature, refer to this page.
  • action: Must be collection.create.
  • 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 & Status Toggles:

  • 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.

For comprehensive details, visit the Flipsnack API Reference for collection.create.

API 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.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.update.
  • collectionHash: The flipbook to update.

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, colours 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

For full details, visit the Flipsnack API Reference for collection.update.

API Method: collection.getCollection

Retrieves details of a flipbook.

Required Parameters

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: collection.getCollection.
  • collectionHash: Unique identifier for the collection.

Response

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

For more details, visit the Flipsnack API Reference for collection.getCollection.

API Method: collection.deleteCollection

Delete a collection in Flipsnack.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.deleteCollection.
  • collectionHash: The flipbook to delete.

Response

Returns status code 20 - OK if successful.

For detailed instructions, visit the Flipsnack API Reference for collection.deleteCollection.

API 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

  • apiKey: Your Flipsnack API key.
  • signature: MD5 hash signature.
  • action: Must be collection.setPermissions.
  • collectionHash: The unique hash identifier of the flipbook.
  • permissions: JSON string with a permissions array. Replaces existing list. Must be URL-encoded.

Permissions Payload Structures

  • teammate: Grants workspace accepted reader access. E.g., { "type": "teammate", "group": "mygroup2", "notifyViaEmail": true }.
  • otp: Grants access via One-Time Password email authentication. Email is required. E.g., { "type": "otp", "email": "reader@example.com" }.
  • sso: Grants access through Single Sign-On (SSO) authentication. E.g., { "type": "sso", "group": "mygroup1" }.
  • notifyViaEmail: Optional boolean flag. When true, emails the specified recipients or groups with active invitations.

Removing All Permissions: Send an empty permissions array: { "permissions": [] } to remove all private access rows.

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.

For more details, visit the Flipsnack API Reference for collection.setPermissions.

API Method: collection.getPermissions

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

Required Parameters

  • apiKey: Your Flipsnack API key.
  • signature: MD5 hash signature.
  • action: Must be collection.getPermissions.
  • collectionHash: The unique hash identifier of the 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).

For more details, visit the Flipsnack API Reference for collection.getPermissions.

API Method: collection.getEmbed

Retrieves embed code for a flipbook.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.getEmbed.
  • collectionHash: The hash of the collection to get the embed code.

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.

For detailed instructions, visit the Flipsnack API Reference for collection.getEmbed.

API Method: collection.getStats

Retrieves statistics for a specified collection in Flipsnack.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.getStats.
  • collectionHash: Hash of the flipbook you want statistics for.

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.

For detailed instructions, visit the Flipsnack API Reference for user.getStats.

API Method: collection.getList

Returns a list of flipbooks belonging to the user, from a folder or the whole account.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.getList.

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.

For detailed instructions, visit the Flipsnack API Reference for the collection.getList.

API 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.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be collection.downloadHTML.
  • collectionHash: The hash of the collection to download.

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.

For more details, visit the Flipsnack API Reference for collection.downloadHTML.

API Method: user.getStats

Retrieves global statistics for all flipbooks under the user account.

Required request parameters:

  • apiKey: Your API key.
  • signature: MD5 hash signature.
  • action: Must be user.getStats.

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.

For detailed instructions, visit the Flipsnack API Reference for user.getStats.

API Method: zapier.getZapierLeadFormSample

Provides sample data from lead forms, for Zapier integration.

Required request parameters:

  • apiKey: Your API key.
  • action: Must be zapier.getZapierLeadFormSample.
  • collectionHash: The hash of the collection to retrieve sample data.

Response:

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

For detailed instructions, visit the Flipsnack API Reference for zapier.getZapierLeadFormSample.

Limits worth designing around

These are the ceilings an integration meets in production, not edge cases, so build the retry and the batching in 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.
  • 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.

Important: the developer docs give two different page ceilings: the limitations page says 1,000 pages and status code 35 says 500. Treat 500 as the safe number until the limitations page says otherwise.

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.

Webhooks: let Flipsnack call you

The methods above are requests you make. Webhooks are the other direction. Flipsnack posts to a URL of yours when something happens in a flipbook, so you do not have to poll for it.

  • Order webhooks fire when a reader places a Shopping List order.
  • Contact form webhooks fire when a reader submits a form inside a flipbook.
  • Cart event webhooks fire as a reader builds the cart, covering items added, removed or changed, which is what you want for abandoned-cart flows and live inventory 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, 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

Need expert support?

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