Guide to Using Flipsnack API

Request and response parameters

API Method: collection.create

The collection.create method allows you to upload a single PDF document to create a new collection with a flipbook item in Flipsnack.

Required Request Parameters:

• apiKey: Your unique API key.
• signature: MD5 hash signature.
• action: Must be collection.create.
• file: The PDF file to upload.

Optional Request Parameters:

• fileUrl: URL of a PDF document.
• title: The title of the collection.
• description: Description of the collection.
• width and height: Dimensions of the collection.
• status: private or public.
• playerSettings: Various settings for the flipbook player.

Example Request:

Response:

Returns a JSON object with the collection details, status, and settings.

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

API Method: collection.getCollection

The collection.getCollection method retrieves detailed information about a collection, including configuration parameters and the list of collection items.

Request Parameters:

• apiKey (required): Your API key.
• signature (required): MD5 hash signature.
• action (required): Must be collection.getCollection.
• collectionHash (required): The hash of the collection you wish to retrieve.

Example Request:

Response:

Returns a JSON object containing:

• Collection details (hash, title, description, status, thumbnail URL, etc.)
• List of collection items
• Configuration parameters (width, height, player settings, etc.)
• Flipbook status (processing, complete, failed)

Configuration Parameters:

• collectionWidth: Width in pixels.
• collectionHeight: Height in pixels.
• collectionStatus: Public, editable, or unlisted.
• enableFullScreen: Allows fullscreen mode.
• enableDownload: Displays download button.
• autoFlip: Enables automatic page turning.
• autoFlipDelay: Time in seconds for automatic page turn.
• rightToLeftOrientation: Right to left viewing mode.
• backgroundColor: Background color of the player.

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

API Method: collection.update

The collection.update method updates the settings of an existing collection in Flipsnack.

Required Request Parameters:

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

Optional Request Parameters:

• title: The collection's title.
• description: Description of the collection.
• collectionWidth and collectionHeight: Dimensions of the collection.
• collectionStatus: public, editable, or unlisted.
• enableThumbView, enableToc, showControls, enableDownload, enablePrint, enableFullScreen, enableSearch: Various player settings.
• tooltipsLanguage: Language for tooltips.
• background and color: Background settings.
• autoFlip and autoFlipDelay: Auto-flip settings.
• rightToLeftOrientation: Right-to-left viewing.
• singlePageView: Single page viewing.

Example Request:

Response:

Returns a JSON object with updated collection details.

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

API Method: collection.deleteCollection

The collection.deleteCollection method deletes a specified collection in Flipsnack.

Required Request Parameters:

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

Example Request:

Response:

Returns a status code 20 - OK if successful.

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

API Method: collection.getEmbed

The collection.getEmbed method returns the embed code for a specified collection based on the given parameters.

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.

Example Request:

Response:

Returns a JSON object with the embed code.

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

API Method: collection.getStats

The collection.getStats method 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: The hash of the collection to get statistics.

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.

Example Request:

Response:

Returns a JSON object with statistics, including impressions, views, time spent, downloads, and optional page-specific statistics.

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

API Method: collection.getList

The collection.getList method returns a list of collections belonging to your user.

Required Request Parameters:

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

Optional Parameters:

• collectionStatus: Type of collection (public, editable, 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.

Example Request:

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 collection.getList.

API Method: collection.downloadHTML

The collection.downloadHTML method allows you to generate and download an HTML package for a specified collection in Flipsnack. This is useful for offline viewing or embedding the collection on a website.

Required Request Parameters:

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

Example Request:

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:

1. Request HTML Package: Send the request with the necessary parameters.
2. Check Status: The response will include a status code and, if successful, a URL to download the package.
3. 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

The user.getStats method retrieves global statistics for your user, including impressions, views, time spent, and downloads for all collections.

Required Request Parameters:

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

Example Request:

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

The zapier.getZapierLeadFormSample method retrieves sample data for lead forms, useful for integration with Zapier.

Required Request Parameters:

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

Example Request:

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.