# API documentation Get up and running with Flipsnack public API This API allows developers to write applications that interact with Flipsnack from a 3rd party system. The API exposes different methods to manage a single workspace's flipbooks, based on an API key provided for that specific user. ## What can you do with the API: * Upload files to create new flipbooks; * Update flipbook settings; * Delete flipbooks; * Get flipbook data; * Retrieve a list of flipbooks for the user who owns the API key; * Retrieve statistics data for an entire user workspace or a single flipbook; * Get the embed code for a specific flipbook. * Generate the HTML package and get the download url for a flipbook. To protect our users' data and the Flipsnack application, our public API imposes certain [limitations](/api-limitations). Abusing the API will get your API key banned and you will not be able to access Flipsnack data as a result. Your API key is available during your subscription period. Once your subscription ends, the API key will be disabled automatically. # Getting started ## 1. Apply for an API key The first thing you need to do is [obtain an API key](/how-to-get-an-api-key). The API keys are available only for users with active Enterprise accounts. Please note that the API key is secret and you should not disclose or share it with anyone else. ## 2. Choose an API method Flipsnack API has two endpoints which receive API calls: * **** - for upload requests * **** - for the all other requests Once you identify the correct endpoint, you must select one of the API methods, depending on what action you wish to perform. You can select the action from the API methods listed in the API Reference. Each method must receive a set of parameters. You must send these parameters as part of the URL when using HTTP GET requests or inside the HTTP body for HTTP POST requests. When uploading files you must use HTTP POST with encoding multipart/form-data. All other requests must be made using HTTP GET. ## 3. Make a request The request (either through POST or GET) must contain at least 3 parameters. The mandatory parameters are: * **apiKey** - required for authentication. We associate the user to the API key provided * **signature** - required for authentication. Please read [How to sign requests](/how-to-sign-a-request) to see how to calculate the parameter * **action** - specifies which method should be executed Example: ``` https://api.flipsnack.com/v1/?apiKey={apiKey}&signature={signature}&action={method} ``` ## 4. Parse the response The response from the API will be in JSON format. ⓘ *Requesting XML formatted response using the format parameter is deprecated and we strongly recommend you to avoid it.* The response body will contain 3 parameters: * **code** - the status code of the response (20 for 'OK'). See other [status codes](/api-status-codes) returned by the API * **status** - the status message corresponding to the status code * **data** - the actual data sent from the API server If the request does not need data returned from the server (e.g. delete operations) or if the response is an error, the **data** parameter will be missing. ## 5. Handle errors In case of errors, the response will contain the error code (the **code** parameter) along with the error message associated (the **status** parameter). Error messages have a code value higher than 20. Please see the list of [status codes](/api-status-codes) for more details. **Note:** Status messages are only descriptive. We recommend you to use the status code when checking API responses. You can find the explanation for each status code in the [status codes](/api-status-codes) list. # API status codes ## Status codes The API server responds contain a status code specifying the status of the response. The table below lists all the status codes and messages returned by the API server: | Code | Message | Explanation | | ---- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 20 | OK | The request was processed successfully. The response might also contain the **data** parameter containing data returned from the server. | | 22 | Maintenance mode | The API servers have entered in maintenance mode and cannot complete any requests. In this case you should try again later. | | 30 | Missing mandatory parameter | The request does not contain one or more required parameters. There are at least 3 required parameters for every request: **apiKey**, **signature** and **action**. Other methods may also have extra mandatory parameters. Please check the API Reference for more information. | | 31 | Requests per second limit exceeded | There were too many requests per second made with the same API key. | | 32 | Requests per minute limit exceeded | There were too many requests per minute made with the same API key. | | 33 | Uploads per month exceeded | You have exceeded the maximum number of uploads allowed per month. | | 34 | File size too large | The file you have uploaded has a size that exceeds the maximum file size allowed, or a raster logo exceeds 1000 x 1000 px. For more information please see the [limitations](/api-limitations) imposed by the API. | | 35 | Flipbook maximum pages number exceeded | You have uploaded a document that exceeds the maximum of 500 pages allowed. For more information please see the [limitations](/api-limitations) imposed by the API. | | 36 | Multiple files upload not allowed | Flipsnack API allows only one file per upload request. Upload requests are made via the [collection.create](/api-reference/api-method-collection.create) method. | | 37 | Delete flipbook not available for this flipbook | *deprecated* | | 38 | Flipbook is in processing state | Publishing a flipbook may take a few seconds. You can check the **collectionStatus** at regular intervals (e.g., every few seconds) using the [collection.getCollection](/api-reference/api-method-collection.getcollection) method. Continue making requests to [collection.getCollection](/api-reference/api-method-collection.getcollection) until the **collectionStatus** has a value other than processing. | | 40 | Bad request | | | 41 | Invalid credentials | The API key provided in the request is invalid. | | 42 | Invalid action | The API method you specified in the request is incorrect. Please see the API Reference for the list of possible methods. | | 43 | Forbidden | You are not allowed to access the specified flipbook: it has been deleted or the flipbook belongs to another user. | | 44 | Invalid signature | The signature you provided is incorrect - it does not match the request. | | 45 | Invalid file format | The file you are trying to upload has an incorrect file type, extension/MIME mismatch, or is a corrupt upload. For more information please see the [limitations](/api-limitations) imposed by the API. | | 46 | Invalid flipbook hash | You are trying to access a flipbook that does not exist. | | 47 | Invalid flipbook hash | You are trying to access a flipbook that does not exist. | | 50 | Operation failed | An error occurred on the server and the request could not be completed. In this case you should resend the request after a few seconds. If the request still fails after several attempts, please contact us. | # API limitations All users with valid Enterprise accounts can access the Flipsnack API. Using our API, you can manage your publications just as you would in our online application. To ensure fair usage and stability of our infrastructure we have set a few limitations to this API. **Note:** These limitations apply only to Flipsnack API and not the online application. ## Upload limitations The number of uploads via the API is limited as follows: | | Enterprise | | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Uploads | Max 1000 uploads per month. This option is available only for Enterprise users when purchasing or upgrading to an Enterprise account. | | | **Important**: The limitation for the number of flipbooks in your workspace is also applied. | In case you exceed the number of uploads per month, the request will return the error code "32 - Uploads per month limit exceeded". **Note:** Only successful upload requests from [`collection.create`](/api-reference/api-method-collection.create) are counted toward the monthly upload limitations. ## File limitations The files uploaded via the API must be valid files of type PDF or JPG. You can make upload requests to create new flipbooks from PDF documents. | Action | Limitations | | ----------------- | -------------------------------------------------------------------------------------------------- | | collection.create | | You can upload a single PDF document using the `collection.create` API call. If you have multiple PDF files for a single flipbook, you should merge them into a single file and upload it. ## Request limitations We limit Flipsnack API calls (both read and write) to a maximum of **5 calls per second** and **60 calls per minute** to ensure that system resources are distributed evenly. If you exceed the number of requests per second the API call will return the error code "31 - Requests per second limit exceeded". We recommend spreading requests over a larger time period so you can avoid receiving this error. Also, caching the request results on your side is strongly recommended. ## Error codes Here are the error codes related to API limitations: | Code | Message | Explanation | | ---- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 31 | Requests per second limit exceeded | There were too many requests per second made with the same API key. | | 32 | Requests per minute limit exceeded | There were too many requests per minute made with the same API key. | | 33 | Uploads per month exceeded | You have exceeded the maximum number of uploads allowed per month. | | 34 | File size too large | The file you have uploaded has a size that exceeds the maximum allowed file size. For more information please see the limitations imposed by the API. | | 35 | Flipbook maximum pages number exceeded | You have uploaded a document that exceeds the maximum of 500 pages allowed. For more information please see the limitations imposed by the API. | | 36 | Multiple files upload not allowed | Flipsnack API allows only one file per upload request. Upload requests are made via the [collection.create](/api-reference/api-method-collection.create) method. | # How to get an API key API keys are available only for valid Enterprise accounts. To get an API key sign into your account and open the **Settings** page, **Integrations** tab. Here you will find the **Flipsnack API** section where you can generate/regenerate your **API key** and **secret key.** The API key and secret key are generated for you alone. You should make sure that they remain secret and others do not have access to them. If someone finds out your API key and secret key there is a **Regenerate Api Keys** button which will generate you a new set of keys. # How to sign a request All requests to Flipsnack API must contain an API key provided by us along with the signature of the request. This signature is calculated using an API Secret Key which we provide along with the API key. The signature proves that you are the owner of the account making the requests. **Note:** These keys are secret and they should not be disclosed or shared with anyone else. Flipsnack does know your API key and secret key and no one who legitimately represents Flipsnack will ask for these keys. Signing a Flipsnack API request is a easy: 1. Sort the request parameters alphabetically, but exclude the signature and file parameter (e.g `action=3, collectionHash=1, apiKey=2 results to action=3, apiKey=2, collectionHash=1`). 2. Create a string by concatenating the API secret key and request key-value pairs which were ordered alphabetically (e.g. `secretKeyaction3apiKey2collectionHash1`). 3. The signature is the MD5 hash of the previous string. 4. Include the signature parameter to the API request (e.g. `signature=26e781d3d1751d82ec284acf4a019def`). If the request is incorrectly signed the API will return with the error code "44 - Invalid signature". **Example:**\ We need to get information about the collection identified with the hash `fxh4k89`. The API key is `45FD-267-7SG7832` and the API secret key is `123ABCDE-456-7890-FGH`. In this case the request parameters are: * `action=collection.getCollection` * `collectionHash=fxh4k89` * `apiKey=45FD-267-7SG7832` Next, we concatenate the secret key to the previous list: ``` 123ABCDE-456-7890-FGHactioncollection.getCollectionapiKey45FD-267-7SG7832collectionHashfxh4k89 ``` The MD5 hash generated for the previous string is 26e781d3d1751d82ec284acf4a019def. This hash is finally assigned to the **signature** parameter. The final request would look like this: ```bash https://api.flipsnack.com/v1/?action=collection.getCollection&collectionHash=fxh4k89&apiKey=45FD-267-7SG7832&signature=26e781d3d1751d82ec284acf4a019def ``` **Note:** The API key, secret key and flipbook hash specified above are all fictional and are used for example purposes only. # collection.create Uploads a single PDF document and creates a flipbook with a single item (flipbook). **Note:** Requests must be made to ****. Once the upload has finished, the flipbook is created and the PDF document starts the conversion process. Converting a PDF document into a flipbook might take up to several minutes, depending on the size of the document. The API method will return a response as soon as the document is finished uploading. You can check the status of the flipbook item using the [`collection.getCollection`](/api-reference/api-method-collection.getcollection) method. It will let you know if the document is still converting, has finished conversion, or if the conversion process has failed. Once the API call is successful, even if the document fails to convert, the request is counted in the monthly upload counts. If the request fails, the request is not taken into consideration for the monthly upload counts. You can now customize the player (logo, background image, background audio, appearance, navigation, sharing, interaction, and tracking) in the same `collection.create` call. When uploading any customization file (`logoImage`, `backgroundImage`, or `backgroundAudio`), send the request as **POST** with **`multipart/form-data`**. If you use `fileUrl` without a local `file` upload, customize asset files cannot be attached in the same request unless you also send multipart file fields. In that case, create the flipbook first and upload customize assets later with `collection.update`. ## Request parameters
NameTypeDescription
NameTypeDescription
apiKey (required)stringThe API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials".
signature (required)stringThe signature must be calculated by you and added to the request. See How to sign a request for more information.If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature".
action (required)stringThe API method that should be called. In this case the value should be collection.create. If it is not specified, the request will return the error code "30 - Missing mandatory parameter".
file (required)file

The PDF document that should be uploaded.

Documents can be uploaded either using a local file, through the file parameter, or from an external URL, using the fileUrl parameter. You must specify at least one of them. If both parameters are specified, the API will take into consideration only the file parameter.

If neither file or fileUrl are specified the request will return the error code "30 - Missing mandatory parameter".

Also, file uploads are bound to API limitations.

fileUrl (required)string

The URL of a PDF document.

Documents can be uploaded either using a local file, through the file parameter, or from an external URL, using the fileUrl parameter. You must specify at least one of them. If both parameters are specified, the API will take into consideration only the file parameter.

If neither file or fileUrl are specified the request will return the error code "30 - Missing mandatory parameter".

Also, file uploads are bound to API limitations.

titlestringThe title of the collection. This title will appear on the collection's direct link and in the My Collections page. By default, if a title is not given, Flipsnack will try to extract the title from the uploaded document.
descriptionstringThe description of the collection. By default, during the conversion process, Flipsnack extracts the first few words from the document. You can overwrite that description with yours, using this parameter.
collectionWidthnumberThe embed width of the player (measured in pixels).

Default: 650.
collectionHeightnumberThe embed height of the player (measured in pixels).

Default: 385.
collectionStatusstring

The type of collection. Possible values are public, editable, unlisted and private.

Public collections are listed on your public profile and in search results.They are publicly available to other users.

Editable collections are not published. They must be published manually from the Flipsnack editor or have their status updated using the collection.update method.

Unlisted collections are published but not listed on your profile page and in search results. Other users may view them only if they receive a direct link or an embedded player from you.

Published with restricted access. Configure access with collection.setPermissions.

Default: public.

showControlsbooleanIf set to true, then the navigation controls will be displayed in normal mode

Default: false.
enableDownloadbooleanIf set to true, displays the download button in the player menu. The menu is displayed only when the player is in fullscreen.

Default: true.
enablePrintbooleanIf set to true, displays the print button in the player menu. The menu is displayed when the player is in fullscreen.

Default: true.
enableFullScreenbooleanIf set to true, allows the player to enter fullscreen mode.

Default: true.
enableSearchbooleanIf set to true, displays the search button in the player menu. The menu is displayed only when the player is in fullscreen.

If there is no text to search within the current collection, the search button is displayed, but disabled.

Default: true.
tooltipsLanguagestringSelects the language for the tooltips displayed in the player. Possible languages are: Basque, Bosanski, Català, Czech, Dansk, Deutsch, English, Español, כשר, Française, ελληνικά, Hrvatski, Indonesian, Italiano, Magyar, Nederlands, Nederlands, Norsk, Polski, Português, Português do Brasil, Română, Pусский, Cрпски, Slovene, Suomi, Slovak, Swedish, Turkish.

Default: English.
backgroundstringThe background color of the player. Possible values are color, transparent and image. If set to transparent, the player is displayed with no background. Background color value can be set using the color parameter, explained below. When using the image option, upload the image with the backgroundImage option as multipart/form-data.

Default: color.
colorstring

The background color of the player, specified as a hexadecimal value or CSS gradient. Accepted values are 444444, #ff0000 and linear-gradient(...)/radial-gradient(...) expressions.

If the background is set to transparent, the player will ignore the color parameter.

Default: 444444.

autoFlipbooleanIf set to true, allows the player to automatically turn the pages of the flipbook. The pages turn after a time specified by the autoFlipDelay parameter.

Default false.
autoFlipDelaynumberSpecifies the time in seconds for pages to turn automatically. If autoFlip is false, this parameter is ignored.

Default: 6.
rightToLeftOrientationbooleanIf set to true, allows the flipbook to be viewed from right to left:the first page is starts from the end, as viewed in normal mode. This option is useful for documents written in right to left languages.

Default: false.
singlePageViewbooleanIf set to true, allows the flipbook to be viewed a single page at a time.

Default: false.
logoUrlstringURL opened when the viewer clicks the logo. Upload the logo image using the logoImage parameter.
folderstring

The folder path where the collection will be added in your account.

  • A folder name must contain only english letters, digits and spaces. Also a folder name must start and end with a letter or a digit, not a space.
  • The folder name is case insensitive. "My Folder" will be the same with "my folder".
  • If the parameter is not specified or empty string is provided the collection will be displayed on main folder (root).
  • The path must not include first or last slash character (/).
  • Eg: folder1

You can specify a folder structure up to 3 levels.

  • If a deeper folder is specified, it will be ignored.
  • in a structure, folder names must be separated with a slash character (/).
  • Eg: folder1/folder2/folder3

If the folder already exists in your account the collection will be added in that folder, otherwise the folder structure will be created and, after that, the collection will be added in that folder.

logoImagefileLogo image uploaded as multipart/form-data. Replaces a separate collection.setLogo call during create.
logoLinkstringAlias for logoUrl (click-through URL).
backgroundImagefileBackground image uploaded as multipart/form-data. Use with background=image.
backgroundScaleTypestringBackground image scaling when using an image background. Values: scaleCrop, center, tile. Default when uploading: scaleCrop.
backgroundAudiofileBackground audio uploaded as multipart/form-data.
backgroundAudioEnabledbooleanEnables/disables background audio. Default when uploading a new file: true.
backgroundAudioLoopbooleanIf true, audio loops. Default: false.
backgroundAudioAutoplaybooleanIf true, audio starts on open. Default: false.
playerSkinstringPlayer skin: classic, default (case-insensitive).
playerAccentColorstringAccent color, e.g. #ff0000.
pageTransitionstringDesktop transition: flip, slide, scroll (case-insensitive).
mobilePageTransitionstringMobile transition: flip, slide, scroll (case-insensitive).
layoutStylestringLayout: smartView, singlePage, doublePage (case-insensitive). Takes precedence over singlePageView.
showPageShadowsbooleanIf true, displays page shadows.
enableThumbViewbooleanShows the thumbnail navigator.
navigationArrowsbooleanShows previous/next arrows.
enableRemoteControlbooleanEnables remote control.
enableTocbooleanEnables table of contents (PDF TOC when available).
startWithTOCOpenbooleanOpens the TOC panel on load. Requires enableToc=true and a PDF with TOC.
enableShareOptionsbooleanEnables share options in the player menu. Preferred over deprecated per-network params.
shareLinkbooleanEnables share by link.
### Customization assets limits Player customization uploads are validated before storage. Invalid files return an error and are not applied. | Field | Formats | Max size | Other limits | | --------------- | ------------------------------- | ---------------------- | -------------------------------- | | logoImage | JPEG, PNG, GIF, WebP, AVIF, SVG | 2 MB raster, 10 MB SVG | Raster logos: max 1000 × 1000 px | | backgroundImage | JPEG, PNG, GIF, WebP, AVIF | 20 MB | — | | backgroundAudio | MP3, MPEG | 20 MB | — | MIME type is detected server-side. The file extension must match the detected content type. ## Response parameters If the upload is successful, the API call returns information about the flipbook which was just created.
NameTypeDescription
NameTypeDescription
collectionHashstringThe hash for the newly created flipbook. If the flipbook status is editable the generated hash will be temporary. Once the flipbook is published, a new, final hash will be generated for it.
collectionTitlestringThe title of the flipbook.
collectionDescriptionstringThe description of the flipbook. It can be specified in the creation parameters or generated by the conversion system.
collectionStatusstring

Possible values are:

  • public: The flipbook is published and accessible to the public.
  • editable: The flipbook can be modified by the owner or authorized users.
  • unlisted: The flipbook is published but not publicly accessible without a direct link.
  • processing: The flipbook is published but not yet complete.

While in processing:

  • the collection.update and collection.downloadHTML5 endpoints are unavailable.
  • the public link for the flipbook may not yet be functional.

Publishing a flipbook may take a few seconds. You can check the collectionStatus at regular intervals (e.g., every few seconds) using the collection.getCollection method. Continue making requests to collection.getCollection until the collectionStatus has a value other than processing.

coverImagestringThe url of the flipbook's thumbnail image. This thumbnail is generated from the first page of the first flipbook item.
collectionPageCountnumberThe number of pages in the flipbook, for all the flipbook items.
createdDatedateThe date when the flipbook was created (not necessarily published).
publishDatedateThe date when the flipbook was published.
directLinkstringThe public link of the flipbook, which becomes active within a few seconds.
flipbookPageCountnumberThe number of pages of the flipbook item.

For flipbook created with the API, collectionPageCount and flipbookPageCount should have the same value.
settingsobjectAn object containing the configuration parameters of the flipbook, as set from the API call. See the list below.
collectionItemsarrayThe list of flipbook items belonging to the flipbook. In case of flipbooks created using the API, the list contains a single item.

The parameters of the collection item are listed below.
### **Configuration parameters**
NameTypeDescription
NameTypeDescription
collectionWidthnumberThe embed width of the player (measured in pixels).
collectionHeightnumberThe embed height of the player (measured in pixels).
collectionStatusstringThe type of collection. Possible values are public, editable and unlisted.

Public collections are listed on your public profile and in search results. They are publicly available to other users.

Editable collections are not published. They must be published manually from the Flipsnack editor or updated using the collection.update method.

Unlisted collections are published but not listed on your profile page and in search results. Other users may view them only if they receive a direct link or an embedded player from you.
enableDownloadbooleanIf set to true, displays the download button in the player menu. The menu is displayed only when the player is in fullscreen.
enableFullScreenbooleanIf set to true, allows the player to enter fullscreen mode.
enableSearchbooleanIf set to true, displays the search button in the player menu. If there is no text to search within the current collection item, the search button is displayed as disabled.
tooltipsLanguagestringSelects the language for the tooltips displayed in the player. Possible languages are: Basque, Bosanski, Català, Czech, Dansk, Deutsch, English, Español, כשר, Française, ελληνικά, Hrvatski, Indonesian, Italiano, Magyar, Nederlands, Nederlands, Norsk, Polski, Português, Português do Brasil, Română, Pусский, Cрпски, Slovene, Suomi, Slovak, Swedish, Turkish.
transparentBackgroundbooleanIf set to true, the player is displayed with no background.
backgroundColorstringThe background color of the player, specified as a hexadecimal value. If the transparentBackground is set to true, the player will ignore the backgroundColor parameter.
backgroundScaleTypestringThe scale mode of images used as background for the player. Possible values are scaleCrop, center and tile. Background images can be set using the collection.setBackgroundImage method.
autoFlipbooleanIf set to true, allows the player to automatically turn the pages of the flipbook. The pages turn after a time specified by the autoFlipDelay parameter.
autoFlipDelaynumberSpecifies the time in seconds for pages to turn automatically. If autoFlip is false, this parameter is ignored.
rightToLeftOrientationbooleanIf set to true, allows the flipbook to be viewed from right to left: the first page is starts from the end as viewed in normal mode. This option is useful for documents written in right to left languages.
singlePageViewbooleanIf set to true, allows the flipbook to be viewed a single page at a time.
logoUrl (DEPRECATED)stringThe URL of the logo image. A logo image can be set only by uploading it with the collection.setLogo method.
shareFacebook (DEPRECATED)booleanIf set to true, the player displays a Facebook sharing option in the player menu, in fullscreen mode.
shareTwitter (DEPRECATED)booleanIf set to true, the player displays a Twitter sharing option in the player menu, in fullscreen mode.
shareGooglePlus (DEPRECATED)booleanIf set to true, the player displays a Google+ sharing option in the player menu, in fullscreen mode.
sharePinterest (DEPRECATED)booleanIf set to true, the player displays a Pinterest sharing option in the player menu, in fullscreen mode.
shareEmail (DEPRECATED)booleanIf set to true, the player displays an email sharing option in the player menu, in fullscreen mode.
shareLinkText (DEPRECATED)stringThe link opened from the link sharing option, within the player. By default, this link is the direct link of the collection.
playerSkinstringPlayer skin.
playerAccentColorstringAccent color.
pageTransitionstringDesktop page transition.
mobilePageTransitionstringMobile page transition.
layoutStylestringPage layout.
showPageShadowsbooleanPage shadows enabled.
enableThumbViewbooleanThumbnail navigator.
navigationArrowsbooleanNavigation arrows.
enableRemoteControlbooleanRemote control.
enableTocbooleanTable of contents.
startWithTOCOpenbooleanTOC open on load.
enableShareOptionsbooleanShare menu enabled.
shareLinkbooleanShare by link.
animatedInteractionsbooleanAnimated interactions.
highlightsOnLinksbooleanLink highlights.
textSelectionbooleanText selection.
autodetectLinksbooleanAuto-detected links.
googleAnalyticsIDstringGA measurement ID.
allowIPAnonymizationbooleanGA IP anonymization.
googleTagManagerIDstringGTM container ID.
colorstringBackground color (hex or gradient).
### **Flipbook item parameters**
NameTypeDescription
NameTypeDescription
flipbookHashstringThe hash generated for the flipbook item.
flipbookPageCountnumberThe number of pages of the flipbook item.
flipbookTitlestringThe title of the flipbook.
flipbookDescriptionstringThe description of the flipbook.
extensionstringThe extension of the document that the flipbook is based on. Extensions can be pdf, jpg or png.
convertStatusstring

The status of the flipbook specifies if it has finished converting or if it is still in the process of conversion.

Possible values are:

  • PROCESSING
  • FAILED
  • COMPLETE

Converting a PDF document is a time consuming process. You can check the status of a flipbook at a few seconds intervals by using the collection.getCollection method. The requests to collection.getCollection should be made until the flipbook has completed or failed converting.

## Error codes For a complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # POST curl -X POST "https://upload.flipsnack.com/v1/" \ -F 'file=@"mydocs/document.pdf";filename="document.pdf"' \ -F "action=collection.create" \ -F "apiKey=" \ -F "collectionStatus=public" \ -F "title=Lore Ipsim" \ -F "signature=" ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Branded create (logo + background + audio) ```bash curl -X POST \ https://upload.flipsnack.com/v1/ \ -F action=collection.create \ -F apiKey= \ -F signature= \ -F file=@/path/to/document.pdf \ -F title="Branded Flipbook" \ -F collectionStatus=private \ -F background=image \ -F backgroundScaleType=scaleCrop \ -F logoLink=https://example.com \ -F logoImage=@/path/to/logo.png \ -F backgroundImage=@/path/to/background.jpg \ -F backgroundAudio=@/path/to/track.mp3 \ -F backgroundAudioEnabled=true \ -F backgroundAudioLoop=true ``` ### Gradient background ```bash curl -X POST \ https://upload.flipsnack.com/v1/ \ -F action=collection.create \ -F apiKey= \ -F signature= \ -F file=@/path/to/document.pdf \ -F background=color \ -F 'color=linear-gradient(180deg, #1a1a2e 0%, #16213e 100%)' ``` #### Tracking settings ```bash curl -X POST \ https://upload.flipsnack.com/v1/ \ -F action=collection.create \ -F apiKey= \ -F signature= \ -F file=@/path/to/document.pdf \ -F googleAnalyticsID=G-XXXXXXX \ -F googleTagManagerID=GTM-XXXXXX \ -F allowIPAnonymization=1 ``` ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "collectionHash": "d3m0h45h", "collectionTitle": "Lorem ipsum", "collectionStatus": "published", "coverImage": "https://cdn.flipsnack.com/collections/items/7c5e600d4459fe4e04d23ae5ei188777/covers/page_1/medium", "directLink": "https://www.flipsnack.com/user/lorem-ipsum.html", "createdDate": "2015-06-09 01:43:05", "publishDate": "2015-06-09 01:43:07", "collectionPageCount": 2, "collectionItems": [ { "flipbookHash": "7c5e600d4459fe4e04d23ae5ei188777", "flipbookPageCount": "2", "flipbookTitle": "Lorem ipsum", "flipbookDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "extension": "pdf", "convertStatus": "COMPLETE" } ], "settings": { "collectionWidth": "640", "collectionHeight": "385", "enableFullScreen": "true" } } } ``` {% endtab %} {% endtabs %} # collection.getCollection Returns information about a flipbook. The information contains configuration parameters for the player and the list of flipbook items. **Note:** Requests must be made to ****. You can also use this method at regular time intervals to check if an uploaded document has finished converting. This could be done right after a [collection.create](/api-reference/api-method-collection.create) method call. If the document's status is either complete or failed, you can stop checking its status. ## Request parameters | Name | Type | Description | | ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information.If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.getCollection*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook you wish to update. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | ## Response parameters If the upload is successful, the API call returns information about the flipbook which was just created. | Name | Type | Description | | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collectionHash | string | The hash for the newly created flipbook. If the flipbook status is *editable* the generated hash will be temporary. Once the flipbook is published, a new, final hash will be generated for it. | | collectionTitle | string | The title of the flipbook. | | collectionDescription | string | The description of the flipbook. It can be specified in the creation parameters or generated by the conversion system. | | collectionStatus | string |

Possible values are:

  • public: The flipbook is published and accessible to the public.
  • editable: The flipbook can be modified by the owner or authorized users.
  • unlisted: The flipbook is published but not publicly accessible without a direct link.
  • processing: The flipbook is published but not yet complete.

While in processing:

  • the collection.update and collection.downloadHTML5 endpoints are unavailable.
  • the public link for the flipbook may not yet be functional.

Publishing a flipbook may take a few seconds. You can check the collectionStatus at regular intervals (e.g., every few seconds) using the collection.getCollection method. Continue making requests to collection.getCollection until the collectionStatus has a value other than processing.

| | coverImage | string | The url of the flipbook's thumbnail image. This thumbnail is generated from the first page of the first flipbook item. | | collectionPageCount | number | The number of pages in the flipbook, for all the flipbook items. | | createdDate | date | The date when the flipbook was created (not necessarily published). | | publishDate | date | The date when the flipbook was published. | | directLink | string | The public link of the flipbook. | | flipbookPageCount | number |

The number of pages of the flipbook item.

For flipbooks created with the API, collectionPageCount and flipbookPageCount should have the same value.

| | settings | object | An object containing the [configuration parameters](/api-reference/api-method-collection.create#configuration-parameters) of the flipbook, as set from the API call. [See the list below.](/api-reference/api-method-collection.create#configuration-parameters) | | collectionItems | array |

The list of flipbook items belonging to the flipbook. In case of flipbooks created using the API, the list contains a single item.

The parameters of the collection item are listed below.

| ### **Configuration parameters** | Name | Type | Description | | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collectionWidth | number | The embed width of the player (measured in pixels). | | collectionHeight | number | The embed height of the player (measured in pixels). | | collectionStatus | string |

The type of collection. Possible values are public, editable and unlisted.

Public collections are listed on your public profile and in search results. They are publicly available to other users.

Editable collections are not published. They must be published manually from the Flipsnack editor or updated using the collection.update method.

Unlisted collections are published but not listed on your profile page and in search results. Other users may view them only if they receive a direct link or an embedded player from you.

| | enableDownload | boolean | If set to *true*, displays the download button in the player menu. The menu is displayed only when the player is in fullscreen. | | enableFullScreen | boolean | If set to *true*, allows the player to enter fullscreen mode. | | enableSearch | boolean | If set to *true*, displays the search button in the player menu. If there is no text to search within the current collection item, the search button is displayed as disabled. | | tooltipsLanguage | string | Selects the language for the tooltips displayed in the player. Possible languages are: Basque, Bosanski, Català, Czech, Dansk, Deutsch, English, Español, כשר, Française, ελληνικά, Hrvatski, Indonesian, Italiano, Magyar, Nederlands, Nederlands, Norsk, Polski, Português, Português do Brasil, Română, Pусский, Cрпски, Slovene, Suomi, Slovak, Swedish, Turkish. | | transparentBackground | boolean | If set to *true*, the player is displayed with no background. | | backgroundColor | string | The background color of the player, specified as a hexadecimal value. If the **transparentBackground** is set to *true*, the player will ignore the **backgroundColor** parameter. | | autoFlip | boolean | If set to *true*, allows the player to automatically turn the pages of the flipbook. The pages turn after a time specified by the **autoFlipDelay** parameter. | | autoFlipDelay | number | Specifies the time in seconds for pages to turn automatically. If **autoFlip** is *false*, this parameter is ignored. | | rightToLeftOrientation | boolean | If set to *true*, allows the flipbook to be viewed from right to left: the first page is starts from the end as viewed in normal mode. This option is useful for documents written in right to left languages. | | singlePageView | boolean | If set to *true*, allows the flipbook to be viewed a single page at a time. | | logoUrl (DEPRECATED) | string | *This parameter is deprecated and will no longer return valid values, if any.* | | shareFacebook (DEPRECATED) | boolean | *This parameter is deprecated and will no longer return valid values, if any.* | | shareTwitter (DEPRECATED) | boolean | *This parameter is deprecated and will no longer return valid values, if any.* | | shareGooglePlus (DEPRECATED) | boolean | *This parameter is deprecated and will no longer return valid values, if any.* | | sharePinterest (DEPRECATED) | boolean | *This parameter is deprecated and will no longer return valid values, if any.* | | shareEmail (DEPRECATED) | boolean | *This parameter is deprecated and will no longer return valid values, if any.* | | shareLinkText (DEPRECATED) | string | *This parameter is deprecated and will no longer return valid values, if any.* | ### **Flipbook item parameters** | Name | Type | Description | | ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | flipbookHash | string | The hash generated for the flipbook item. | | flipbookPageCount | number | The number of pages of the flipbook item. | | flipbookTitle | string | The title of the flipbook. | | flipbookDescription | string | The description of the flipbook. | | extension | string | The extension of the document that the flipbook is based on. Extensions can be pdf, jpg or png. | | convertStatus | string | The status of the flipbook specifies if it has finished converting or if it is still in the process of conversion. Possible values are *PROCESSING*, *FAILED* and *COMPLETE*. | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.getCollection \ -d apiKey= \ -d collectionHash=d3m0h45h \ -d signature= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "collectionHash": "d3m0h45h", "collectionTitle": "Lorem ipsum", "collectionStatus": "published", "coverImage": "https://cdn.flipsnack.com/collections/items/7c5e600d4459fe4e04d23ae5ei188777/covers/page_1/medium", "directLink": "https://www.flipsnack.com/user/lorem-ipsum-d3m0h45h.html", "createdDate": "2015-06-09 01:43:05", "publishDate": "2015-06-09 01:43:07", "collectionPageCount": 2, "collectionItems": [ { "flipbookHash": "7c5e600d4459fe4e04d23ae5ei188777", "flipbookPageCount": "2", "flipbookTitle": "Lorem ipsum", "flipbookDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "extension": "pdf", "convertStatus": "COMPLETE" } ], "settings": { "collectionWidth": "640", "collectionHeight": "385", "enableFullScreen": "true" } } } ``` {% endtab %} {% endtabs %} # collection.update Updates the settings of an existing flipbook. **Note:** * requests must be made to **** * this method is not available while the flipbook is in the processing state * `collection.update` supports both GET and POST: * GET — backward compatible. Use for metadata and text/boolean/numeric setting updates (no file uploads). * POST with `multipart/form-data` — required when uploading `logoImage`, `backgroundImage`, or `backgroundAudio`. All other parameters can be sent as form fields in the same POST request. * When you upload a customize asset on an already published flipbook, the API republishes automatically so the public player serves the new logo, background, or audio. ### Request method | Method | Content-Type | Use when | | ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | GET | Query string | Updating title, description, collectionStatus, player settings, tracking IDs, colors, booleans, etc. No file uploads. | | POST | multipart/form-data | Uploading or replacing logoImage, backgroundImage, and/or backgroundAudio. | ## Request parameters | Name | Type | Description | | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.update*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook you wish to update. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | | title | string | The title of the flipbook. This title will appear on the flipbook's direct link and in the My Flipbooks page. By default, if a title is not given, Flipsnack will try to extract the title from the uploaded document. | | description | string | The description of the flipbook. By default, during the conversion process, Flipsnack extracts the first few words from the document. You can overwrite that description with yours, using this parameter. | | collectionWidth | number |

The embed width of the player (measured in pixels).

Default: 650.

| | collectionHeight | number |

The embed height of the player (measured in pixels).

Default: 385.

| | collectionStatus | string |

The type of flipbook. Possible values are public, editable, unlisted and private.

Public flipbooks are listed on your public profile and in search results. They are publicly available to other users.

Editable collections are not published. They must be published manually from the Flipsnack editor or have their status updated using the collection.update method.

Unlisted flipbooks are published but not listed on your profile page and in search results. Other users may view them only if they receive a direct link or an embedded player from you.

Private flipbooks are published with restricted access. Configure access with collection.setPermissions.

Note: Once a flipbook receives the public status, it cannot be changed to unlisted, even if the current status is set to editable. But unlisted flipbooks can be changed to public flipbooks.

Default: public.

| | enableThumbView | boolean |

If set to true, displays the thumbnail viewer in the player. The thumbnail viewer is displayed only when the player is in fullscreen.

Default: true.

| | enableToc | boolean |

If set to true and if the pdf has a table of contents the player will display it.

Default: false.

| | showControls | boolean |

If set to true, then the navigation controls will be displayed in normal mode

Default: false.

| | enableDownload | boolean |

If set to true, displays the download button in the player menu. The menu is displayed only when the player is in fullscreen.

Default: true.

| | enablePrint | boolean |

If set to true, displays the print button in the player menu. The menu is displayed when the player is in fullscreen.

Default: true.

| | enableFullScreen | boolean |

If set to true, allows the player to enter fullscreen mode: a "Click to read" button is displayed.

Default: true.

| | enableSearch | boolean |

If set to true, displays the search button in the player menu. The menu is displayed only when the player is in fullscreen.

If there is no text to search within the current flipbook item, the search button is displayed, but disabled.

Default: true.

| | tooltipsLanguage | string |

Selects the language for the tooltips displayed in the player. Possible languages are: Basque, Bosanski, Català, Czech, Dansk, Deutsch, English, Español, כשר, Française, ελληνικά, Hrvatski, Indonesian, Italiano, Magyar, Nederlands, Nederlands, Norsk, Polski, Português, Português do Brasil, Română, Pусский, Cрпски, Slovene, Suomi, Slovak, Swedish, Turkish.

Default: English.

| | background | string |

The background color of the player. Possible values are color, transparent and image. If set to transparent, the player is displayed with no background. If set to image, upload backgroundImage as multipart/form-data. Background color value can be set using the color parameter, explained below.

Default: color.

| | color | string |

The background color of the player, specified as a hexadecimal value. If the background is set to transparent, the player will ignore the color parameter.

Default: 444444.

| | autoFlip | boolean |

If set to true, allows the player to automatically turn the pages of the flipbook. The pages turn after a time specified by the autoFlipDelay parameter.

Default false.

| | autoFlipDelay | number |

Specifies the time in seconds for pages to turn automatically. If autoFlip is false, this parameter is ignored.

Default: 6.

| | rightToLeftOrientation | boolean |

If set to true, allows the flipbook to be viewed from right to left: the first page is starts from the end, as viewed in normal mode. This option is useful for documents written in right to left languages.

Default: false.

| | singlePageView | boolean |

If set to true, allows the flipbook to be viewed a single page at a time.

Default: false.

| | logoImage | file | Logo image uploaded as multipart/form-data. Upload only when replacing the logo file. | | logoUrl | string | URL opened when the viewer clicks the logo. Upload the logo image with logoImage. Update this click-through URL without re-uploading the image. | | logoLink | string | Alias for logoUrl (click-through URL). Update the click-through URL without re-uploading the image. | | backgroundImage | file | Background image uploaded as multipart/form-data. Use with background=image. | | backgroundScaleType | string | Background image scaling when using an image background. Values: scaleCrop, center, tile. Default when uploading: scaleCrop. | | backgroundAudio | file | Background audio uploaded as multipart/form-data. Upload only when replacing the track. | | backgroundAudioEnabled | boolean | Enables/disables background audio. Use to change playback without re-uploading. Default when uploading a new file: true. | | backgroundAudioLoop | boolean | If true, audio loops. Default: false. | | backgroundAudioAutoplay | boolean | If true, audio starts on open. Default: false. | | playerSkin | string | Player skin: classic, default (case-insensitive). | | playerAccentColor | string | Accent color, e.g. #ff0000. | | pageTransition | string | Desktop transition: flip, slide, scroll (case-insensitive). | | mobilePageTransition | string | Mobile transition: flip, slide, scroll (case-insensitive). | | layoutStyle | string | Layout: smartView, singlePage, doublePage (case-insensitive). Takes precedence over singlePageView. | | showPageShadows | boolean | If true, displays page shadows. | | navigationArrows | boolean | Shows previous/next arrows. | | enableRemoteControl | boolean | Enables remote control. | | startWithTOCOpen | boolean | Opens the TOC panel on load. Requires enableToc=true and a PDF with TOC. | | enableShareOptions | boolean | Enables share options in the player menu. Preferred over deprecated per-network params. | | shareLink | boolean | Enables share by link. | | shareFacebook (DEPRECATED) | boolean | If true, shows Facebook share in the player menu (fullscreen). Deprecated — use enableShareOptions. | | shareTwitter (DEPRECATED) | boolean | If true, shows Twitter/X share. Deprecated. | | shareGooglePlus (DEPRECATED) | boolean | If true, shows Google+ share. Deprecated. | | sharePinterest (DEPRECATED) | boolean | If true, shows Pinterest share. Deprecated. | | shareEmail (DEPRECATED) | boolean | If true, shows email share. Deprecated. | | shareLinkText (DEPRECATED) | string | Custom link for the link-sharing option. Deprecated. | | animatedInteractions | boolean | Animates interaction elements in the player. | | highlightsOnLinks | boolean | Visually highlights link areas. | | textSelection | boolean | Allows viewers to select text. | | autodetectLinks | boolean | Auto-converts URLs in the document to clickable links. | | googleAnalyticsID | string | Google Analytics measurement ID, e.g. G-XXXXXXX. | | allowIPAnonymization | boolean | If true, anonymizes IPs in GA tracking. | | googleTagManagerID | string | GTM container ID, e.g. GTM-XXXXXX. | | mergeFlips | boolean | Merge PDFs/flipbooks where supported. | | password | string | Password for password-protected private viewing where supported. | ## Customize asset limits Customize uploads are validated before storage. Invalid files return an error and are not applied. | Field | Formats | Max size | Other limits | | --------------- | ------------------------------- | ---------------------- | -------------------------------- | | logoImage | JPEG, PNG, GIF, WebP, AVIF, SVG | 2 MB raster, 10 MB SVG | Raster logos: max 1000 × 1000 px | | backgroundImage | JPEG, PNG, GIF, WebP, AVIF | 20 MB | — | | backgroundAudio | MP3, MPEG | 20 MB | — | MIME type is detected server-side. The file extension must match the detected content type. If a customize upload fails validation, the update is rejected and existing customize settings remain unchanged. ## Response parameters If the request is successful, the API call returns information about the specified flipbook. This action method has the same response as [collection.getCollection](/api-reference/api-method-collection.getcollection) method. The settings object in the response includes all player options applied by the update, including appearance, navigation, sharing, interaction, tracking, and customize assets. Poll collection.getCollection after publish/processing if you need to confirm values while collectionStatus is processing. ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. | Code | When | | ---- | -------------------------------------------------------------------------------- | | 34 | Customize file too large, or raster logo exceeds 1000 × 1000 px | | 38 | Flipbook still publishing/processing (retry after collectionStatus ≠ processing) | | 40 | Wrong HTTP method (e.g. POST used on a GET-only action), or invalid payload | | 45 | Invalid customize file format | | 50 | Update failed (e.g. JSON update error) | ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.update \ -d apiKey= \ -d collectionHash=d3m0h45h \ -d height=600 \ -d title=Lorem%20ipsum%20dolor \ -d signature= \ -d width=800 ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Upload logo and background (POST) ``` curl -X POST \ https://api.flipsnack.com/v1/ \ -F action=collection.update \ -F apiKey= \ -F signature= \ -F collectionHash= \ -F background=image \ -F backgroundScaleType=scaleCrop \ -F logoLink=https://example.com \ -F logoImage=@/path/to/logo.png \ -F backgroundImage=@/path/to/background.jpg ``` ### Upload background audio (POST) ``` curl -X POST \ https://api.flipsnack.com/v1/ \ -F action=collection.update \ -F apiKey= \ -F signature= \ -F collectionHash= \ -F backgroundAudio=@/path/to/track.mp3 \ -F backgroundAudioEnabled=true \ -F backgroundAudioLoop=true \ -F backgroundAudioAutoplay=false ``` ### Update tracking (GET - no file upload) ``` curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.update \ -d apiKey= \ -d signature= \ -d collectionHash= \ -d googleAnalyticsID=G-XXXXXXX \ -d googleTagManagerID=GTM-XXXXXX \ -d allowIPAnonymization=1 ``` ### Gradient background (GET) ``` curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.update \ -d apiKey= \ -d signature= \ -d collectionHash= \ -d background=color \ -d 'color=linear-gradient(180deg, ##1a1a2e 0%, ##16213e 100%)' ``` ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "collectionHash": "d3m0h45h", "collectionTitle": "Lorem ipsum dolor", "collectionStatus": "published", "coverImage": "https://d1dhn91mufybwl.cloudfront.net/collections/items/7c5e600d4459fe4e04d23ae5ei188777/covers/page_1/medium", "directLink": "https://www.flipsnack.com/user/lorem-ipsum.html", "createdDate": "2015-06-09 01:43:05", "publishDate": "2015-06-09 01:43:07", "collectionPageCount": 2, "collectionItems": [ { "flipbookHash": "7c5e600d4459fe4e04d23ae5ei188777", "flipbookPageCount": "2", "flipbookTitle": "Lorem ipsum", "flipbookDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", "extension": "pdf", "convertStatus": "COMPLETE" } ], "settings": { "collectionWidth": "800", "collectionHeight": "600", "enableFullScreen": "true" } } } ``` {% endtab %} {% endtabs %} # collection.getPermissions This method returns the private access permissions configured for a flipbook. ## Request method `collection.getPermissions` uses **GET**. Endpoint: ``` https://api.flipsnack.com/v1/ ``` ## Request parameters
NameTypeRequiredDescription
actionstringYesMust be collection.getPermissions.
apiKeystringYesYour Flipsnack API key.
signaturestringYesRequest signature generated with your API secret.
collectionHashstringYesThe hash of the flipbook.
## Permission object The response contains a `permissions` array. Each item has one of these `type` values:
TypeFieldsDescription
teammatenoneAll accepted readers from the workspace have access.
teammateemailOne accepted reader from the workspace has access.
teammategroupAll readers from the specified workspace group have access.
otpemailA viewer has access through one-time password email authentication.
ssononeAll SSO-authenticated viewers for the workspace/profile have access.
ssogroupSSO-authenticated viewers from the specified group have access.
`group` is a field containing the group name. It is not a permission `type`. `notifyViaEmail` is not returned by `collection.getPermissions`. It is a request-only option for `collection.setPermissions`. ## Request example ```bash curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.getPermissions \ -d apiKey= \ -d signature= \ -d collectionHash= ``` ## Response examples Recommended usage is to keep permissions of the same `type` in one access list. ### Teammate response ```json { "code": 20, "status": "OK", "data": { "permissions": [ { "type": "teammate", "group": "mygroup2" }, { "type": "teammate", "email": "maya.reader@example.com" } ] } } ``` ### SSO response ```json { "code": 20, "status": "OK", "data": { "permissions": [ { "type": "sso", "group": "mygroup1" } ] } } ``` ### OTP response ```json { "code": 20, "status": "OK", "data": { "permissions": [ { "type": "otp", "email": "olivia.reader@example.com" }, { "type": "otp", "email": "ethan.viewer@example.com" } ] } } ``` If no private access permissions are configured: ```json { "code": 20, "status": "OK", "data": { "permissions": [] } } ``` ## Notes * The method is available only for flipbooks eligible for private access permissions. Private flipbooks can be created or set using the [`collection.create`](/api-reference/api-method-collection.create) and [`collection.update`](/api-reference/api-method-collection.update) actions. * The order of returned permissions follows the saved access rows. * Unknown/deleted groups or readers that no longer resolve may be omitted from the response. ## Error responses All errors return JSON with at least `code` and `status`. Some failures also include a `data` object. ### Request, auth, and access errors
CodeStatusWhen
30Missing mandatory parameterapiKey, signature, action, or collectionHash is missing.
31Requests per second limit exceededAPI rate limit exceeded.
32Requests per minute limit exceededAPI rate limit exceeded.
41Invalid credentialsThe API key is invalid.
44Invalid signatureThe request signature is invalid (Flipsnack/MCP keys).
46Invalid collection hashThe collection hash does not exist.
43ForbiddenThe collection does not belong to the API key workspace, is deleted, or the tenant does not match.
40Bad RequestThe action was sent with the wrong HTTP method (must be GET).
### Permissions-specific errors
CodeStatusWhen
48Permissions are only available for published private flipbooksThe flipbook is not published, is not private, or has a password set.
40Bad RequestThe permissions service rejected the request (see data.errors when present).
50Operation failedThe permissions service returned an unexpected response.
Example — not eligible: ```json { "code": 48, "status": "Permissions are only available for published private flipbooks" } ``` # collection.setPermissions This method sets the private access permissions configured for a flipbook. ## Request method `collection.setPermissions` uses **GET**. Endpoint: ``` https://api.flipsnack.com/v1/ ``` The `permissions` parameter is a JSON string. URL-encode it when sending the request. ## Request parameters
NameTypeRequiredDescription
actionstringYesMust be collection.setPermissions.
apiKeystringYesYour Flipsnack API key.
signaturestringYesRequest signature generated with your API secret.
collectionHashstringYesThe hash of the flipbook.
permissionsJSON stringYesJSON object with a permissions array. This replaces the existing access list.
## Permissions payload The `permissions` parameter must be a JSON object with this structure: ```json { "permissions": [ { "type": "teammate", "group": "mygroup2", "notifyViaEmail": true } ] } ``` To remove all private access rows, send an empty array: ```json { "permissions": [] } ``` All permission objects in a non-empty `permissions` array must use the same `type`. For example, multiple `teammate` entries are valid in one request, but combining `teammate` and `otp` entries in the same request returns a bad request error. ## Permission object fields
NameTypeRequiredDescription
typestringYesPermission type. Possible values: teammate, otp, sso.
emailstringConditionalEmail address for otp or teammate access. Required for otp. Optional for teammate. Not supported for sso.
groupstringOptionalGroup name. Available only for teammate and sso. group is a field, not a permission type.
notifyViaEmailbooleanNoIf true, sends notification emails for this permission entry during this collection.setPermissions call. If omitted, it is treated as false.
`email` and `group` cannot be used together in the same permission object. ## Permission types ### teammate Grants access to accepted readers from the workspace.
ShapeDescription
{ "type": "teammate" }Grants access to all accepted readers from the workspace.
{ "type": "teammate", "email": "reader@example.com" }Grants access to one accepted reader from the workspace.
{ "type": "teammate", "group": "mygroup2" }Grants access to accepted readers from the specified workspace group.
If a teammate group name does not exist, that permission entry is skipped. If a teammate email is not an accepted reader in the workspace, that permission entry is skipped. ### otp Grants access through one-time password email authentication. | Shape | Description | | -------------------------------------------------- | ------------------------------------------------- | | `{ "type": "otp", "email": "reader@example.com" }` | Grants OTP access to the specified email address. | `email` is required for `otp`. ### sso Grants access through SSO authentication. | Shape | Description | | ---------------------------------------- | ------------------------------------------------------------------------- | | `{ "type": "sso" }` | Grants access to all SSO-authenticated viewers for the workspace/profile. | | `{ "type": "sso", "group": "mygroup1" }` | Grants access to SSO-authenticated viewers from the specified group. | `email` is not supported on `sso` permissions. Use `teammate` for per-email workspace reader access. If an SSO group name does not exist, that permission entry is skipped. ## Notification behavior `notifyViaEmail` can be used on any permission type: ```json { "type": "teammate", "notifyViaEmail": true } ``` For `{ "type": "teammate", "notifyViaEmail": true }`, all accepted readers from the workspace are notified. For group or email entries, only the matching group members or email recipient are notified. `notifyViaEmail` is evaluated for the current `collection.setPermissions` request. If you call `collection.setPermissions` again with `notifyViaEmail: true`, emails can be sent again. If `notifyViaEmail` is omitted, it is treated as `false`. `notifyViaEmail` is not returned by `collection.getPermissions`. ## Payload examples Each request must send permissions of the same `type`. ### Teammate permissions ```json { "permissions": [ { "type": "teammate", "group": "mygroup2", "notifyViaEmail": true }, { "type": "teammate", "email": "maya.reader@example.com", "notifyViaEmail": true }, { "type": "teammate", "email": "noah.reader@example.com", "notifyViaEmail": false } ] } ``` ### OTP permissions ```json { "permissions": [ { "type": "otp", "email": "olivia.reader@example.com", "notifyViaEmail": true }, { "type": "otp", "email": "ethan.viewer@example.com", "notifyViaEmail": false } ] } ``` ### SSO permissions ```json { "permissions": [ { "type": "sso", "group": "mygroup1", "notifyViaEmail": true } ] } ``` ## Request examples ### Set teammate permissions ```bash PERMISSIONS='{ "permissions": [ { "type": "teammate", "group": "mygroup2", "notifyViaEmail": true }, { "type": "teammate", "email": "maya.reader@example.com", "notifyViaEmail": true }, { "type": "teammate", "email": "noah.reader@example.com", "notifyViaEmail": false } ] }' curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.setPermissions \ -d apiKey= \ -d signature= \ -d collectionHash= \ --data-urlencode "permissions=${PERMISSIONS}" ``` ### Set SSO permissions ```bash curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.setPermissions \ -d apiKey= \ -d signature= \ -d collectionHash= \ --data-urlencode 'permissions={"permissions":[{"type":"sso","group":"mygroup1","notifyViaEmail":true}]}' ``` ### Give access to all accepted workspace readers and notify them ```bash curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.setPermissions \ -d apiKey= \ -d signature= \ -d collectionHash= \ --data-urlencode 'permissions={"permissions":[{"type":"teammate","notifyViaEmail":true}]}' ``` ### Remove all permissions ```bash curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.setPermissions \ -d apiKey= \ -d signature= \ -d collectionHash= \ --data-urlencode 'permissions={"permissions":[]}' ``` ## Response examples The response returns the saved permissions after invalid/skipped entries are removed. ### Teammate response ```json { "code": 20, "status": "OK", "data": { "permissions": [ { "type": "teammate", "group": "mygroup2" }, { "type": "teammate", "email": "maya.reader@example.com" } ] } } ``` ### SSO response ```json { "code": 20, "status": "OK", "data": { "permissions": [ { "type": "sso", "group": "mygroup1" } ] } } ``` After removing all permissions: ```json { "code": 20, "status": "OK", "data": { "permissions": [] } } ``` ## Skipped entries Some permission entries are skipped instead of returning an error:
EntryBehavior
teammate with a non-existent groupSkipped.
teammate with an email that is not an accepted workspace readerSkipped.
sso with a non-existent groupSkipped.
If all entries are skipped, the flipbook has no saved access rows and the response contains an empty `permissions` array. ## Validation errors Invalid payload or permission objects return **code `40` (Bad Request)** with details in `data.errors`: ```json { "code": 40, "status": "Bad Request", "data": { "errors": [ "Permissions cannot combine multiple types" ] } } ``` Examples: | Case | Behavior | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `permissions` is missing or is not valid JSON | Code `30` (missing parameter) or code `40` with `Invalid permissions payload`. | | `permissions.permissions` is not an array | Code `40` with `Invalid permissions payload`. | | Unknown `type` value | Code `40` with `Invalid permission type at index N (got '…')`. | | Multiple permission `type` values in the same `permissions` array | Code `40` with `Permissions cannot combine multiple types`. | | `email` and `group` are both set on the same permission | Code `40` with `Permission at index N cannot have both email and group`. | | `group` is used with `otp` | Code `40` with `Permission at index N cannot have group (type=otp; group allowed only on teammate/sso)`. | | `otp` without `email` | Code `40` with `Permission at index N requires an email`. | | `sso` with `email` | Code `40` with `SSO permission cannot include an email - use teammate or user for per-email access`. | | Invalid email format | Code `40` with `Invalid email at index N`. | | Duplicate permission entry | Code `40` with `Duplicate permission at index N`. | | `notifyViaEmail` is not a boolean | Code `40` with `Invalid permissions format.`. | | OTP permissions not on plan | Code `40` with `OTP permissions are not available on your plan`. | | SSO permissions not on plan | Code `40` with `SSO permissions are not available on your plan`. | | SSO not enabled for workspace | Code `40` with `SSO is not enabled for this workspace`. | ## Error responses All errors return JSON with at least `code` and `status`. Validation failures on this action also include `data.errors` (string array). ### Request, auth, and access errors
CodeStatusWhen
30Missing mandatory parameterapiKey, signature, action, collectionHash, or permissions is missing.
31Requests per second limit exceededAPI rate limit exceeded.
32Requests per minute limit exceededAPI rate limit exceeded.
41Invalid credentialsThe API key is invalid.
44Invalid signatureThe request signature is invalid (Flipsnack/MCP keys).
46Invalid collection hashThe collection hash does not exist.
43ForbiddenThe collection does not belong to the API key workspace, is deleted, or the tenant does not match.
40Bad RequestThe action was sent with the wrong HTTP method (must be GET).
### Permissions-specific errors
CodeStatusWhen
48Permissions are only available for published private flipbooksThe flipbook is not published, is not private, or has a password set.
38Collection is in progress. Please try again laterThe flipbook is still publishing; retry after collectionStatus is no longer processing.
40Bad RequestInvalid permissions payload or validation/plan/SSO errors (see data.errors).
50Operation failedThe permissions service returned an unexpected response.
Example — not eligible: ```json { "code": 48, "status": "Permissions are only available for published private flipbooks" } ``` Example — validation error: ```json { "code": 40, "status": "Bad Request", "data": { "errors": [ "OTP permissions are not available on your plan" ] } } ``` # collection.deleteCollection Deletes the specified flipbook. Please note that you only have access to your own flipbooks. **Note:** Requests must be made to ****. ## Request parameters | Name | Type | Description | | ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.deleteCollection*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook you want to delete. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | ## Response parameters If the request is successful, The API does not send back data. It only responds with status code "20 - OK". ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.deleteCollection \ -d apiKey= \ -d collectionHash=d3m0h45h \ -d signature= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK" } ``` {% endtab %} {% endtabs %} # collection.getEmbed Returns the embed code for a specified flipbook based on a set of embed parameters. **Note:** Requests must be made to ****. ## Request parameters | Name | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.getEmbed*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook for which you want the embed code. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | | https (DEPRECATED) | boolean |

If set to true, the embed code will load the player from our HTTPS location.

Default: true.

| | responsive | boolean |

If set to true, the Flipsnack embed will have the width and height set to 100% and it will take the entire size of the container.

Default: false.

| | startPage | number |

The page number where the flipbook will open automatically.

Default: 1.

| | startBook (DEPRECATED) | number |

The player will automatically open the specified flipbook from the flipbook.

Default: 1.

| | width | number | The width of the embed. By default it will have the size specified by the flipbook width parameter. The flipbook width can be set when creating a new flipbook or when editing/updating an existing flipbook. | | height | number | The height of the embed. By default it will have the size specified by the flipbook height parameter. The flipbook height can be set when creating a new flipbook or when editing/updating an existing flipbook. | ## Response parameters | Name | Type | Description | | --------- | ------ | ---------------------------------------------------------------------- | | embedCode | string | The embed code as requested with the API call: iframe or object embed. | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.getEmbed \ -d apiKey= \ -d collectionHash=d3m0h45h \ -d signature= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```javascript { "code": 20, "status": "OK", "data": { "embedCode": "" } } ``` {% endtab %} {% endtabs %} # collection.getStats Returns the statistics for the specified flipbook. **Note:** Requests must be made to ****. ## Request parameters | Name | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.getStats*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook for which you want to get statistics. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | | startDate | string | The start date for statistics interval. Date format must be: YYYY-MM-DD | | endDate | string | The end date for statistics interval. Date format must be: YYYY-MM-DD | | includePageStats | boolean |

If set to true an array with statistics for each page will be returned.

Default: false.

| ## Response parameters | Name | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | impressions | number | The number of impressions of the flipbook. Impressions are counted each time the player is loaded. | | views | number | The number of views of the flipbook. Views are counted each time a user interacts with the player. | | time\_spent | number | The total time spent is measured in seconds and shows how much time people spend viewing the flipbook. | | likes (DEPRECATED) | number | The number of likes your flipbook has received on Flipsnack. | | downloads | number | The number of times your documents were downloaded from the flipbook. | | pages | array |

This array will be returned only if the includePageStats is set to true and the request format is json.

This will be an array/list of properties containing: page (page index), time\_spent (in seconds), clicks, views for each page.

| ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} 
# GET   
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.getStats \
     -d apiKey=<YOUR-API-KEY> \
     -d collectionHash=d3m0h45h \
     -d signature=<YOUR-REQUEST-SIGNATURE>
{% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "impressions": 723, "views": 1240, "time_spent": 53, "downloads": 4, "pages": [ { "page": 1, "time_spent": 127443, "clicks": 392, "views": 4529 }, { "page": 2, "time_spent": 89382, "clicks": 171, "views": 4130 } ] } } ``` {% endtab %} {% endtabs %} # collection.getList Returns a list of flipbooks belonging to your user. **Note:** Requests must be made to ****. ## Request parameters | Name | Type | Description | | -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.getList*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionStatus | string |

The type of flipbook. Possible values are public, editable and unlisted.

Public flipbooks are listed on your public profile and in search results. They are publicly available to other users.

Editable flipbooks are not published. They must be published manually from the Flipsnack editor or updated using the collection.update method.

Unlisted flipbooks are published but not listed on your profile page and in search results. Other users may view them only if they receive a direct link or an embedded player from you.

Note: If you do not specify a flipbook status, the API will return all flipbooks within the specified range, regardless of their types.

| | query | string | A search query to help narrow down search results. This could be a keyword or a phrase to search through the title and description of the flipbook. | | from | number |

The index of the starting record for the returned list. You can limit the number of results by specifying the index for the first record (parameter from) and the last record (parameter to).

By default, if you do not specify the from and to parameters, the API call returns the first 50 records.

Default: 0.

| | to | number |

The index of the last record for the returned list. You can limit the number of results by specifying the index for the first record (parameter from) and the last record (parameter to).

By default, if you do not specify the from and to parameters, the API call returns the first 50 records.

Default: 50.

| | orderBy | string |

The field after which the returned list will be ordered. Possible values are date\_published, date\_created and name.

Default: date\_published.

| | orderMode | string |

Specifies if the list will be ordered ascending or descending. Possible values are asc and desc.

Default: desc.

| | folder | string |

The folder path where flipbooks are stored in your account.

  • A folder name must contain only english letters, digits and spaces. Also a folder name must start and end with a letter or a digit, not a space.
  • The folder name is case insensitive. "My Folder" will be the same with "my folder".
  • If the parameter is not specified or empty string is provided the list of all flipbooks in your account will be retrieved (this is for backward compatibility).
  • If you want to retrieve only the flipbooks from the root folder (that are not added to a folder yet) you should provide the slash (/) character alone.
  • The path must not include first or last slash character (/), excepting the case when you provide the slash (/) character alone as mentioned above.
  • Eg: folder1

You can specify a folder structure up to 3 levels.

  • If a deeper folder is specified, it will be ignored.
  • in a structure, folder names must be separated with a slash character (/).
  • Eg: folder1/folder2/folder3

If the folder does not exists or there are no flipbooks in that folder you will receive 0 results.

| ## Response parameters | Name | Type | Description | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collectionsCount | string |

The total number of flipbooks that match the request. This number does not take into consideration the limits specified at the API call.

For example, your request could match 100 flipbooks, but it returns only the ones within the limits specified by from and to parameters.

| | collections | object | An object containing the list of flipbooks returned that match the requested criteria. The parameters for each flipbook are described in [the list below](/api-reference/api-method-collection.getlist#collection-parameters). | ### Flipbook parameters | Name | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | collectionHash | string | The hash for the newly created flipbook. If the flipbook status is *editable* the generated hash will be temporary. Once the flipbook is published, a new, final hash will be generated for it. | | collectionTitle | string | The title of the flipbook. | | collectionStatus | string |

Possible values are:

  • public: The flipbook is published and accessible to the public.
  • editable: The flipbook can be modified by the owner or authorized users.
  • unlisted: The flipbook is published but not publicly accessible without a direct link.
  • processing: The flipbook is published but not yet complete.

While in processing:

  • the collection.update and collection.downloadHTML5 endpoints are unavailable.
  • the public link for the flipbook may not yet be functional.

Publishing a flipbook may take a few seconds. You can check the collectionStatus at regular intervals (e.g., every few seconds) using the collection.getCollection method. Continue making requests to collection.getCollection until the collectionStatus has a value other than processing.

| | coverImage | string | The url of the flipbook's thumbnail image. This thumbnail is generated from the first page of the first flipbook item. | | createdDate | date | The date when the flipbook was created (not necessarily published). | | directLink | string | The public link of the flipbook. | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} 
# GET
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.getList \
     -d apiKey=<YOUR-API-KEY> \
     -d collectionStatus=public \
     -d from=0 \
     -d to=2 \
     -d signature=<YOUR-REQUEST-SIGNATURE>
{% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "collectionsCount": "15", "collections": [ { "collectionHash": "d3m0h45h", "collectionTitle": "Lorem ipsum", "collectionStatus": "public", "publishDate": "2015-06-09 04:50:23", "createdDate": "2015-06-09 04:50:21", "coverImage": "https://files.flipsnack.net/collections/items/913699e80d28331517aee0afci188784/covers/page_1/thumb", "directLink": "https://www.flipsnack.com/user/lorem-ipsum.html" }, { "collectionHash": "fdnlg59t", "collectionTitle": "Official document", "collectionStatus": "public", "publishDate": "2015-06-09 01:42:39", "createdDate": "2015-06-09 01:42:37", "coverImage": "https://files.flipsnack.net/collections/items/0553278b2fd72f91d88224222i188776/covers/page_1/thumb", "directLink": "https://www.flipsnack.com/user/official-document.html" } ] } } ``` {% endtab %} {% endtabs %} # collection.downloadHTML Starts generating the download package and returns the progress status. When the status is complete it also returns the resource url. **Note:** * requests must be made to **** * this method is not available while the flipbook is in the processing state ## Request parameters | Name | Type | Description | | ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *collection.getStats*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook for which you want the download package. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | ## Response parameters | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | string |

The status of the download package. Possible values are

  • PROCESSING: the request is being processed;
  • COMPLETE: the package has been successfully generated;
  • FAILED: the package could not be generated

Generating a download package is a time consuming process. You can check the status at a few second intervals by using the collection.downloadHTML method. The requests to collection.downloadHTML should be made until the download package is generated. If the download package is already generated when the first request to collection.downloadHTML is made, the COMPLETE status will be returned.

| | resourceUrl | string | The url for the download package. The url will expire after one minute due to security reasons. | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=collection.downloadHTML \ -d apiKey= \ -d collectionHash=d3m0h45h \ -d signature= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "status": "COMPLETE", "resourceUrl": "https://cdn.flipsnack.com/sample-path/to-html.zip", } } ``` {% endtab %} {% endtabs %} # user.getStats Returns global statistics for your user. **Note:** * requests must be made to **** * the embedded flipbook may not function properly while the flipbook is in the processing state or the PDF document conversion is incomplete ## Request parameters | Name | Type | Description | | -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See [How to sign a request](/how-to-sign-a-request) for more information. If the parameter is missing the request will return with error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be *user.getStats*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | ## Response parameters | Name | Type | Description | | ------------------ | ------ | -------------------------------------------------------------------------------------------------------- | | impressions | number | The number of impressions for all the flipbooks. Impressions are counted each time the player is loaded. | | views | number | The number of views for all the flipbooks. Views are counted each time a user interacts with the player. | | time\_spent | number | The total time spent is measured in seconds and shows how much time people spend viewing the flipbooks. | | downloads | number | The number of times your documents were downloaded from your flipbooks. | | api\_uploads\_left | number | The number of uploads left via the API. | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=user.getStats \ -d apiKey= \ -d signature= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "code": 20, "status": "OK", "data": { "impressions": 2945, "views": 3719, "time_spent": 154, "downloads": 28, "api_uploads_left": 53 } } ``` {% endtab %} {% endtabs %} # collection.createCatalog Generates a product catalog from feeds and templates. Generates a product catalog by laying out feed products on templates. Generation runs asynchronously. The call returns when the catalog is queued. Poll [collection.getCollection](/api-reference/api-method-collection.getcollection) until the status changes. For static template pages and blank spacers, use `collection.createFromTemplate`. **Note:** Requests must be made to ****. ### Request parameters | Name | Type | Description | | ---------------------- | ----------- | ----------------------------------------------------------------------- | | `apiKey` (required) | string | The API key provided for your user. | | `signature` (required) | string | Request signature. See [How to sign a request](/how-to-sign-a-request). | | `action` (required) | string | Must be `collection.createCatalog`. | | `sections` (required) | JSON string | A JSON-encoded array of feed sections. | | `title` | string | Title of the generated catalog. | | `folder` | string | Destination folder path, such as `Catalogs/2026`. | `sections` is a JSON-encoded string. This allows signatures over flat parameters. ### Sections `sections` is a non-empty ordered array of feed section objects. Only `sectionType: "feed"` is accepted. #### Feed section fields Feed sections lay out products from one or more feeds. Products can be grouped, sorted, and filtered. | Field | Type | Required | Description | | ------------- | --------- | -------- | ------------------------------ | | `sectionType` | string | Yes | Must be `feed`. | | `sources` | object\[] | Yes | Product feeds. | | `templates` | object\[] | Yes | Templates for product layout. | | `groupBy` | object\[] | No | Groups products before layout. | | `sortBy` | object\[] | No | Orders products before layout. | | `filters` | object\[] | No | Include or exclude rules. | **Sources** | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------- | | `sourceHash` | string | Yes | Hash of the product feed. | **Templates** | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------- | | `templateHash` | string | Yes | Hash of the generator template. | Only `templates[0]` is used for product layout. Use separate sections for different templates. **Group products** `groupBy` is evaluated in order. The first entry is the outermost group. | Field | Type | Required | Description | | ----------- | ------- | -------- | --------------------------------------------------- | | `field` | string | Yes | Feed column used for grouping. | | `pageBreak` | boolean | No | Starts a new page for each value. Default: `false`. | **Sort products** `sortBy` is evaluated in order. The first entry is the primary sort key. | Field | Type | Required | Description | | ------- | ------------------- | -------- | ------------------------------------------- | | `field` | string | Yes | Feed column used for sorting. | | `order` | string or string\[] | Yes | `asc`, `desc`, or custom field-value order. | With custom order, unmatched products follow matched products in their relative order. **Filters** `filters` is an ordered array of filter blocks. `include` blocks narrow results. `exclude` blocks remove results. | Field | Type | Required | Description | | ------------ | --------- | -------- | ------------------------------------------ | | `mode` | string | Yes | `include` or `exclude`. | | `match` | string | No | `all` (AND) or `any` (OR). Default: `all`. | | `conditions` | object\[] | Yes | Conditions in this block. | Each condition has these fields: | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------- | | `field` | string | Yes | Feed column. Use `sku` to match SKUs. | | `operator` | string | Yes | Matching operator. See [Operators](#operators). | | `value` | mixed | Yes | String, string array, or numeric-string range. | **Operators** | Operator | Value | Meaning | | ------------ | ---------------------------- | ------------------------------------- | | `in` / `nin` | string\[] | Included / excluded values. | | `eq` / `ne` | string | Equal / not equal. | | `lt` / `lte` | numeric string | Less than / less than or equal. | | `gt` / `gte` | numeric string | Greater than / greater than or equal. | | `between` | `[min, max]` numeric strings | Inclusive range. | | `contains` | string | Field contains the substring. | Numeric operators require numeric strings, such as `"100"`. ### Authentication Sign each request with the secret key associated with `apiKey`: 1. Exclude `signature` from the request parameters. 2. Sort the remaining parameters alphabetically by key. 3. Concatenate them as `key1value1key2value2…`. 4. Prepend the secret key. 5. Generate the MD5 hash of the resulting string. The `sections` value signs as one parameter value. ### Examples #### Request ``` POST https://api.flipsnack.com/v1/ apiKey = YOUR_API_KEY signature = 9f8b1c… (MD5; see Authentication) action = collection.createCatalog title = My Catalog folder = Catalogs/2026 sections = ``` Use this `sections` array before URL or JSON encoding: ```json [ { "sectionType": "feed", "sources": [ { "sourceHash": "abc123sourceHash" }, { "sourceHash": "abc456sourceHash" } ], "templates": [ { "templateHash": "tmplPhonesHash" } ], "groupBy": [ { "field": "Categorias", "pageBreak": true }, { "field": "Marcas", "pageBreak": true } ], "sortBy": [ { "field": "Categorias", "order": "asc" }, { "field": "Marcas", "order": "asc" }, { "field": "storage", "order": "desc" } ], "filters": [ { "mode": "include", "match": "all", "conditions": [ { "field": "Categorias", "operator": "in", "value": ["Phones", "Tablets"] }, { "field": "Marcas", "operator": "in", "value": ["Apple", "Samsung"] } ] }, { "mode": "include", "match": "any", "conditions": [ { "field": "Marcas", "operator": "eq", "value": "Xiaomi" }, { "field": "Tags", "operator": "contains", "value": "featured" } ] }, { "mode": "exclude", "conditions": [ { "field": "Preț", "operator": "between", "value": ["100", "200"] }, { "field": "stock", "operator": "lte", "value": "0" } ] }, { "mode": "exclude", "conditions": [ { "field": "sku", "operator": "in", "value": ["sku123", "456-asda-qwrf-qwe", "789"] } ] } ] }, { "sectionType": "feed", "sources": [{ "sourceHash": "abc123sourceHash" }], "templates": [{ "templateHash": "tmplLaptopsHash" }], "filters": [ { "mode": "include", "conditions": [ { "field": "Categorias", "operator": "in", "value": ["Laptops"] } ] } ] }, { "sectionType": "feed", "sources": [{ "sourceHash": "abc123sourceHash" }], "templates": [{ "templateHash": "tmplDefault2Hash" }], "filters": [ { "mode": "exclude", "conditions": [ { "field": "Categorias", "operator": "in", "value": ["Laptops", "Phones", "Tablets"] } ] } ] } ] ``` ### Response parameters The response returns the new catalog hash. Generation continues in the background. | Name | Type | Description | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `collectionHash` | string | Hash of the newly created catalog. Use it to poll [collection.getCollection](/api-reference/api-method-collection.getcollection). | ```json { "code": 20, "status": "OK", "data": { "collectionHash": "newHash123" } } ``` Poll [collection.getCollection](/api-reference/api-method-collection.getcollection) using the returned `collectionHash`. ### Error codes See [API status codes](/api-status-codes) for all error codes. Validation failures (`code` `40`) can include `data.message` and `data.errors`. ```json { "code": 40, "status": "Bad Request", "data": { "message": "Validation errors", "errors": [ "sections[0].sources: must be provided." ] } } ``` # collection.createFromTemplate Generates a flipbook from static templates and blank pages. Creates a flipbook from ordered static template pages and optional blank spacers. Generation runs asynchronously. The call returns when the flipbook is queued. Poll [collection.getCollection](/api-reference/api-method-collection.getcollection) until `collectionStatus` is no longer `processing`. For product catalogs built from feeds, use [collection.createCatalog](/api-reference/collection.createcatalog). **Note:** Requests must be made to ****. ### Request parameters | Name | Type | Description | | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` (required) | string | API key for your user. Omission returns `30 - Missing mandatory parameter`. An invalid key returns `41 - Invalid credentials`. | | `signature` (required) | string | Request signature. See [How to sign a request](/how-to-sign-a-request). Omission returns `30 - Missing mandatory parameter`. An invalid signature returns `44 - Invalid signature`. | | `action` (required) | string | Must be `collection.createFromTemplate`. Omission returns `30 - Missing mandatory parameter`. | | `sections` (required) | JSON string | JSON-encoded array that defines flipbook pages in order. See [Sections](#sections). Sign this as one flat parameter. | | `title` | string | Title of the generated flipbook. | | `folder` | string | Destination path, such as `Catalogs/2026`. Names use English letters, digits, and spaces. They start and end with a letter or digit. Paths are case-insensitive, support up to three levels, and omit leading or trailing `/`. Omit or leave empty for the root folder. Existing folders are reused; missing folders are created. | ### Sections `sections` is a non-empty ordered array of section objects. Only `static` and `blank` sections are accepted. `feed` sections are rejected. Include at least one `static` section. #### Common fields | Name | Type | Description | | ------------------------ | ------- | ---------------------------------------------------- | | `sectionType` (required) | string | `static` or `blank`. | | `pageBreak` | boolean | Starts this section on a new page. Default: `false`. | #### Static sections Static sections render fixed pages, such as covers, intros, and dividers. | Name | Type | Description | | ---------------------- | --------- | ----------------------------------------------------------------------------- | | `templates` (required) | object\[] | Non-empty array of templates to render in order. See [Templates](#templates). | | `elements` | object\[] | Values injected into layers by name. See [Elements](#elements). | **Templates** | Name | Type | Description | | ------------------------- | ---------- | --------------------------------------------------------------------------------------------------- | | `templateHash` (required) | string | Generator template hash. | | `templatePages` | integer\[] | **Zero-based** indexes in the template page order. Omit for all pages. Invalid indexes are skipped. | **Elements** Elements inject values into named template layers. The `name` matches the layer's `layerLabel` in the template editor. | Name | Type | Description | | ------------------ | ------------------- | ------------------------------------------------------------- | | `name` (required) | string | Template layer name (`layerLabel`). | | `value` (required) | string or string\[] | Text, a URL, or a list of media URLs. | | `style` | object | Style overrides, such as color. Reserved and not yet applied. | #### Blank sections Blank sections insert empty spacer pages. | Name | Type | Description | | ----------- | ------- | ---------------------------------------------- | | `pageCount` | integer | Number of blank pages to insert. Default: `1`. | #### Sections example Use this structure before URL or JSON encoding the `sections` parameter: ```json [ { "sectionType": "static", "templates": [ { "templateHash": "tmplCoverHash", "templatePages": [0] } ], "elements": [ { "name": "Headline1", "value": "Welcome" }, { "name": "Image", "value": "https://example.com/hero.jpg" } ] }, { "sectionType": "blank", "pageCount": 1 }, { "sectionType": "static", "templates": [ { "templateHash": "tmplCoverHash", "templatePages": [1] } ] } ] ``` ### Response parameters A successful request returns the new flipbook hash. Generation continues in the background. | Name | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionHash` | string | New flipbook hash. Poll [collection.getCollection](/api-reference/api-method-collection.getcollection) until `collectionStatus` changes from `processing`. | ### Error codes See [API status codes](/api-status-codes) for all error codes. Validation failures (`code` `40`) can include `data.message` and field-level entries in `data.errors`. ### Examples #### Request {% tabs %} {% tab title="cURL" %} ```bash # POST curl -X POST "https://api.flipsnack.com/v1/" \ -F "action=collection.createFromTemplate" \ -F "apiKey=" \ -F "signature=" \ -F "title=My static book" \ -F "folder=Catalogs/2026" \ -F 'sections=[{"sectionType":"static","templates":[{"templateHash":"tmplCoverHash","templatePages":[0]}],"elements":[{"name":"Headline1","value":"Welcome"}]},{"sectionType":"blank","pageCount":1}]' ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} #### Response {% tabs %} {% tab title="Success" %} ```json { "code": 20, "status": "OK", "data": { "collectionHash": "newHash123" } } ``` {% endtab %} {% tab title="Error" %} ```json { "code": 40, "status": "Bad Request", "data": { "message": "Validation errors", "errors": [ "sections: must include at least one static section." ] } } ``` {% endtab %} {% endtabs %} # zapier.getZapierLeadFormSample Returns information about lead form. The information contains sample data about your fields that might be used for integration. **Note:** Requests must be made to ****. ## Request parameters | Name | Type | Description | | ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey (required) | string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | action (required) | string | The API method that should be called. In this case the value should be *zapier.getZapierLeadFormSample*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | collectionHash (required) | string | The hash of the flipbook you wish to get sample data. If you do not specify a flipbook hash, then the request will return the error code "30 - Missing mandatory parameter". | ## Response parameters | Name | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | number | Your sample data ID | | fields | string |

Your predefined fields as \[key] - value pairs.

Example:

“Phone Number”: “+1 555-555-1234”,

“Email Address”: “”

| ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X GET \ -G \ https://api.flipsnack.com/v1/ \ -d action=zapier.getZapierLeadFormSample \ -d apiKey= \ -d collectionHash= ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="JSON" %} ```json { "data": { "getZapierLeadFormSample": { "id": 1, "Email address": "Your \"Email address\"", "Full name": "Your \"Full name\"", "Phone number": "Your \"Phone number\"", "Country/region": "Your \"Country/region\"", "Website": "Your \"Website\"", "Paragraph": "Your \"Paragraph\"", "Custom input": "Your \"Custom input\"", "GDPR": "Your \"GDPR\"" } } } ``` {% endtab %} {% endtabs %} # products.create Create new products within flipsnack The products.create method allows external systems—such as PIMs, ERPs, or custom integrations—to send product data directly to Flipsnack. Each request must include an apiSecretKey for authentication, a sourceHash to group the products, and a list of product objects. Submitted products become visible in the Automation tab in the Design Studio, replacing the need for manual CSV imports. **Note:** Requests must be made to **** ### Rules & Limitations * Payloads must follow a predefined JSON schema * Up to 500 products per request * Maximum payload size: 200 MB * sourceHash must be generated and persisted by the client and must be a maximum 64-character identifier used to group products under a specific source. Clients are responsible for generating and persisting this value for future updates or deletions * Variants must be nested inside their parent product * Duplicate SKUs within the same request or under the same sourceHash are not allowed ### Feed Organization Clients can submit products under one or multiple sourceHash values, allowing them to manage separate product feeds. **The sourceHash is also required for future updates or deletions.** ## Request parameters | Name | Type | Description | | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

apiKey (required)


| string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See[ How to sign a request](https://developers.flipsnack.com/how-to-sign-a-request) for more information.If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be products.create. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | sourceHash (required) | string | This needs to be a unique identifier within flipsnack to be able to update based on it the products and also to have the possibility to create multiple feeds from the same API | | products (required) | JSON | It’s a JSON containing all the products that are going to pe created | | feedName (required) | string | The name, how the feed will be listed in automation list in app | ### Products example as JSON type Below is an example of the expected JSON structure for products. Notes: * `variants` is optional. If included, it must be an array of objects. * Custom field keys can be any key-value pair, but must not contain dots (`.`) (e.g., use `custom_field` instead of `custom.field`). ```json [ { "type": "string", // required "code": "string", // required "[your_custom_field_1]": "string | number | boolean", "[your_custom_field_2]": "string | number | boolean", "variants": [ // optional { "code": "string", // required "parent_code": "string", // required "[your_custom_field_1]": "string | number | boolean", "[your_custom_field_2]": "string | number | boolean" } ] } ] ``` ## Response parameters | Name | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |

code


| string |

Possible values:

  • 20: When all goes well and action is executed correctly
  • 40: When data submitted has invalid data of wrong format
  • 51: When the mac number of products sent is exceeded
  • 30: Missing a mandatory parameter
| | status | string | Message related to code | | data | JSON | It's a JSON with more details about the response it has a more detailed message about the outcome, errors or data which is an array of exact messages | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X POST https://api.flipsnack.com/v1/ \ -F action=products.create \ -F apiKey= \ -F signature= \ -F sourceHash= \ -F products="” ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="Success" %} ``` { "code": 20, "status":"", "data": { "message":"Products created successfully", "errors":[] } } ``` {% endtab %} {% tab title="Error" %} 
{
    "code": 40,
    "status": "",
    "data": {
        "message": "Invalid or incomplete data sent!",
        "errors": [
            "Variable \"$products\" got invalid value \"\" at \"products[0].discount_price\"; Int cannot represent non-integer value: \"\""
        ]
    }
}
{% endtab %} {% endtabs %} # products.update Update already existing product within flipsnack The products.update method allows external systems (such as a PIM or ERP) to send full or partial product data directly to Flipsnack. Each request has a limitation of 500 products per request and must include an apiKey, signature for authentication, a sourceHash to know exactly which feeds products to update and the product list with the updated fields there is no need to send full products it’s enough to send only the updated fields.The last step is data validation and if all goes well the updated products will be available under the Automation tab in the Design Studio. **Note:** Requests must be made to **** ## Request parameters | Name | Type | Description | | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

apiKey (required)


| string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See[ How to sign a request](https://developers.flipsnack.com/how-to-sign-a-request) for more information.If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be products.update . If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | sourceHash (required) | string | This needs to be a unique identifier within flipsnack to be able to update based on it the products and also to have the possibility to create multiple feeds from the same API | | products (required) | JSON | It’s a JSON containing all the products that are going to pe created | | feedName | string | The name, how the feed will be listed in automation list in app | ### Products example as JSON type Below is an example of the expected JSON structure for products. Notes: * `variants` is optional. If included, it must be an array of objects. * Custom field keys can be any key-value pair, but must not contain dots (`.`) (e.g., use `custom_field` instead of `custom.field`). ```json [ { "type": "string", // required "code": "string", // required "[your_custom_field_1]": "string | number | boolean", "[your_custom_field_2]": "string | number | boolean", "variants": [ // optional { "code": "string", // required "parent_code": "string", // required "[your_custom_field_1]": "string | number | boolean", "[your_custom_field_2]": "string | number | boolean" } ] } ] ``` ### Products JSON Example In the next example there is only one product but you can send a maximum of 500 products per request also the required fields have a comment “// required” all the rest of the fields are optional and need to be sent only if they change ```json [ { "type": "Product", // required "code": "SKU-01-WFW", // required "title": "Women Fine Watch", "category": "Watches", "subcategory": "Women", "country_of_origin": "Japan", "material": "steel", "description": "Imported japanese quartz movement keeps time accurate.", "image_link": "https://cdn.flipsnack.com/images/automation/women-fine-watch-black.jpg;", "sell_price": 35, "currency": "USD", "discount_price": 0, "quantity": true, "MOQ": true, "min_purchasable_qty": 100, "max_purchasable_qty": 100, "attribute_name1": "Color", "attribute_options1": "Silver/Black;Gold/Brown;Gold/Green", "attribute_name2": "size", "attribute_options2": "s;m", "image_attribute": "Color", "shop_element": "AREA", "area_element_tooltip": "Click to view this product", "area_element_color": "#7BC2FF", "area_element_opacity": 20, "shop_button_color": "#0362FC", "shop_button_label": "Add to cart", "shop_label_color": "#ffffff", "shop_button": true, "website_button": false, "website_button_label": "", "website_link": "", "customizable_product": false, "customizable_product_instructions": "", "customizable_product_flat_fee": 100, "customizable_product_per_character": 100, "customizable_product_character_length": 100, "customizable_product_mandatory": false, "variants": [ // optional { "code": "SKU-01-WFW-SB", // required "parent_code": "SKU-01-WFW", // required "image_link": "https://cdn.flipsnack.com/collections/uploads/01793059c4a88ae3d80eb24f45752982", "visible": true, "attribute_options1": "Silver/Black", "attribute_options2": "s", "price": 120, "discount_price": 110 } ] } ] ``` ## Response parameters | Name | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |

code


| string |

Possible values:

  • 20: When all goes well and action is executed correctly
  • 40: When data submitted has invalid data of wrong format
  • 51: When the mac number of products sent is exceeded
  • 30: Missing a mandatory parameter
| | status | string | Message related to code | | data | JSON | It's a JSON with more details about the response it has a more detailed message about the outcome, errors or data which is an array of exact messages | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Examples ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X POST https://api.flipsnack.com/v1/ \ -F action=products.create \ -F apiKey= \ -F signature= \ -F sourceHash= \ -F products="” ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ## Response {% tabs %} {% tab title="Success" %} ``` { "code": 20, "status":"", "data": { "message":"Products updated successfully", "errors":[] } } ``` {% endtab %} {% tab title="Error" %} ```json { "code": 30 "status": "Missing mandatory parameter” "data": { "message":"", "errors":[ Feed name parameter is missing, Products parameter is missing Source hash parameter is missing Products hashes parameter is missing ] } } ``` {% endtab %} {% endtabs %} # products.delete The automation.deleteProducts method allows external systems (such as a PIM or ERP) to remove products data directly from Flipsnack. Each request must include an apiKey, signature for authentication, a sourceHash to know exactly from which feed will the products be removed and the productHashes to be removed.If all products in the feed are deleted, the corresponding feed (source) will also be automatically removed. The results will be available under the Automation tab in the Design Studio. **Note:** Requests must be made to **** ## Request parameters | Name | Type | Description | | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

apiKey (required)


| string | The API key provided for your user. If it is not specified, the request will return the error code "30 - Missing mandatory parameter". If the key is incorrect the request returns the error code "41 - Invalid credentials". | | signature (required) | string | The signature must be calculated by you and added to the request. See[ How to sign a request](https://developers.flipsnack.com/how-to-sign-a-request) for more information.If the parameter is missing the request will return the error code "30 - Missing mandatory parameter". If the signature is incorrect the request will return the error code "44 - Invalid signature". | | action (required) | string | The API method that should be called. In this case the value should be products.update . If it is not specified, the request will return the error code "30 - Missing mandatory parameter". | | sourceHash (required) | string | This needs to be a unique identifier within flipsnack to be able to update based on it the products and also to have the possibility to create multiple feeds from the same API | | productsSKU (required) | array | It’s a list of products SKU. The method accepts one or multiple products SKU to be deleted | ## Response parameters | Name | Type | Description | | ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

code


| string |

Possible values:

  • 20: When all goes well and action is executed correctly
  • 40: When data submitted has invalid data of wrong format
  • 41: Unauthorized access
  • Unexpected error
  • 51: When the max number of products sent is exceeded
  • 30: Missing a mandatory parameter
| | status | string | Message related to code | ## Error codes For complete list of error codes and messages go to [API status codes](/api-status-codes) section. ## Example This is an example of how the list of codes should look to be deleted: SKU-01,SKU-02,SKU-03 We have 3 products to delete. If all the codes are from products, the deletion will be with success. If some of the codes are not correct or there are codes from variation, the deletion will be successful, if at least one is from a product. ### Request {% tabs %} {% tab title="cURL" %} ```bash # GET curl -X POST https://api.flipsnack.com/v1/ \ -F action=products.delete \ -F apiKey= \ -F signature= \ -F sourceHash= \ -F productsSKU="” ``` {% endtab %} {% tab title="HTML" %} ```html
``` {% endtab %} {% endtabs %} ### Response {% tabs %} {% tab title="Success" %} ``` { "code": 20, "status":"", "data": { "message":"Products deleted successfully", "errors": [] } } ``` {% endtab %} {% tab title="Error" %} ```json { "code": 30 "status": "Missing mandatory parameter” "data": { "message":"Products deleted successfully", "errors": ["Products hashes parameter is missing"], } } ``` {% endtab %} {% endtabs %} # Orders Send product orders from catalogs directly to your internal systems using webhooks. You can now connect your own webhook endpoint to receive real-time order data from your interactive catalogs. Just provide the URL of your webhook, and every time a customer submits an order inside one of your flipbooks, we’ll send the full order payload to your endpoint in JSON format. **Returned codes:** when the webhook returns non **2xx** codes, we will consider it a failed request and log the error message. Failed requests are found in the Webhook section of the Integrations page.
#### Restrictions * Only HTTPS endpoints are allowed * Max timeout: 10 seconds (typical) * Retry up to 5 times with exponential backoff * Disabled automatically after 5 failures * Webhook URL cannot require authentication * One webhook per workspace/account #### Important attributes Order JSON
AttributeTypeDescription
typeStringThe type of the event. Make sure you always check the value before processing data you received. For orders, the value should be "orders" (other values may be supported in the future).
order_idStringThe ID of the order as it is recorded in the Flipsnack back-end.
timestampNumericThe timestamp value when the order was received.
datetimeDatetimeThe UTC date and time the order was received by Flipsnack.
custom_fieldsObject

A list of one or more custom fields required by the publisher for buyers to submit. Each field has a 'field_name' (string) and 'field_value' (string) property.
Example:

{
    "field_name": "Full name",
    "field_value": "John Smith"
}
itemsArrayThe list of items specified in the order. Each item is a separate object containing information like SKU, name or price.
total_priceNumberThe total value of the order (if items contain price information).
currencyStringThe currency used for items in the order. If items in the order do not have a price, the currency will not be specified.
Item JSON
AttributeTypeDescription
skuStringThe SKU of the product, as specified in the product feed used by the catalog.
nameStringThe name of the product. In case of product variations, it will contain the variations as well.
quantityNumberThe number of items ordered for a specific product.
discounted_priceNumberThe discounted price of the product. If not specified, no discount was applied.
priceNumberThe full price of the product. If not specified, the item does not have a price.
totalNumberThe line item total (price × quantity). Calculated using discounted_price if available, otherwise price.
imageStringThe URL of the product image.
Below is an example of the JSON structure sent for each order: ```json { "type": "order", "order_id": "1234567", "timestamp": 1763108200, "datetime": "2025-11-14 08:16:40", "flipbook_hash": "tjsdsf9o7k", "flipbook_title": "Summer catalog", "custom_fields": [ { "field_name": "Email address", "field_value": "john.smith@mycompany.com" }, { "field_name": "Full name", "field_value": "John Smith" } ], "items": [ { "sku": "P001", "name": "Scandinavian dining chair with light wood frame and soft fabric seat", "quantity": 3, "discounted_price": 232.99, "price": 327.99, "total": 698.97, "image": "image_url" }, { "sku": "P003", "name": "Modern dining chair with sleek metal frame and fabric upholstery", "quantity": 1, "discounted_price": 242.99, "price": 283.99, "total": 242.99, "image": "image_url" }, { "sku": "P010", "name": "Contemporary two-seater sofa with slim legs and plush cushions", "quantity": 1, "discounted_price": 112.99, "price": 139.99, "total": 112.99, "image": "image_url" }, { "sku": "P002", "name": "Minimalist sectional sofa with low-profile, modular design", "quantity": 2, "discounted_price": 115.99, "price": 142.99, "total": 231.98, "image": "image_url" } ], "total": 1286.93, "currency": "USD" } ``` # Contact forms Send lead information from flipbooks directly to your internal systems using webhooks. You can now connect your own webhook endpoint to receive real-time lead data from your interactive flipbooks. Just provide the URL of your webhook, and every time a lead submits information using a contact form inside one of your flipbooks, we’ll send the data payload to your endpoint in JSON format. **Returned codes:** when the webhook returns non **2xx** codes, we will consider it a failed request and log the error message. Failed requests are found in the Webhook section of the Integrations page.
#### Restrictions * Only HTTPS endpoints are allowed * Max timeout: 10 seconds (typical) * Retry up to 5 times with exponential backoff * Disabled automatically after 5 failures * Webhook URL cannot require authentication * One webhook per workspace/account #### Important attributes Contact form JSON
AttributeTypeDescription
typeStringThe type of the event. Make sure you always check the value before processing data you received. For contact forms, the value should be "contact" (other values may be supported in the future).
timestampNumericThe timestamp value when the contact form data was received.
datetimeDatetimeThe UTC date and time the contact form data was received by Flipsnack.
flipbook_hashStringThe hash of the flipbook that sent the contact form data. This hash can be used to identify the target flipbook using our API.
flipbook_titleStringThe title of the flipbook that sent the contact form. You can use this information to easily identify which flipbook is the source for the contact form data.
dataObject

The data related to the contact form. It contains the information the lead has entered in the contact form. Each data entered by the lead has a field name (string) property and a field value (string).


Example:

{
    "Full name": "John Smith",
    "Email": "johnsmith@mydomain.com"
}
#### **Form data** Please note that the field names in the JSON data will be the ones you specified in the contact form setup as field names for the form. Also, your form may contain less fields or fields with different names.
Field nameTypeDescription
Form nameStringThe name of the form, as specified in the Contact form setup. This field is always set.
Email addressStringThe email of the lead.
First nameStringThe first name of the lead.
Last nameStringThe last name of the lead.
Full nameStringThe full name of the lead.
Phone numberStringThe phone number of the lead.
Country/regionStringThe country of the lead.
WebsiteStringThe website of the lead.
Dropdown fieldStringThe value of the option selected in the drop down field.
ParagraphStringThe long form text entered by the lead in the paragraph field.
Custom inputStringThe custom text entered by the lead in the custom input field.
Below is an example of the JSON structure sent for a sample custom form with default field names: ```json { "type": "contact", "timestamp": 1773232688, "datetime": "2026-03-11 12:38:08", "flipbook_hash": "dzp8uj9xu3", "flipbook_title": "Gardening in April", "data": { "Form name": "April Brochure Contact Form", "Email address": "john.smith@mywebsite.com", "First name": "John", "Last name": "Smith", "Full name": "John Smith", "Phone number": "-", "Country/region": "UK", "Website": "https://www.mywebsite.com", "Dropdown field": "Option 2", "Paragraph": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam eget purus venenatis, commodo nisl in, auctor magna. Phasellus ut ultricies neque, sit amet luctus felis. In et pellentesque diam. In euismod mauris a justo auctor dapibus.", "Custom input": "This is information entered in the custom input." } } ```