collection.update

Updates the settings of an existing flipbook.

Note:

• requests must be made to https://api.flipsnack.com/v1

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

cURL

# GET
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.update \
     -d apiKey=<YOUR-API-KEY> \
     -d collectionHash=d3m0h45h \
     -d height=600 \
     -d title=Lorem%20ipsum%20dolor \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d width=800

HTML

<form method="get" action="https://api.flipsnack.com/v1/">
    <input type="hidden" name="action" value="collection.update">
    <input type="hidden" name="apiKey" value="<YOUR-API-KEY>">
    <input type="text" name="title">
    <input type="text" name="width">
    <input type="text" name="height">
    <input type="hidden" name="signature" value="<YOUR-REQUEST-SIGNATURE>">
    <button type="submit">Submit</button>
</form>

Upload logo and background (POST)

curl -X POST \
https://api.flipsnack.com/v1/ \
-F action=collection.update \
-F apiKey=<YOUR-API-KEY> \
-F signature=<YOUR-REQUEST-SIGNATURE> \
-F collectionHash=<COLLECTION-HASH> \
-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=<YOUR-API-KEY> \
-F signature=<YOUR-REQUEST-SIGNATURE> \
-F collectionHash=<COLLECTION-HASH> \
-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=<YOUR-API-KEY> \
-d signature=<YOUR-REQUEST-SIGNATURE> \
-d collectionHash=<COLLECTION-HASH> \
-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=<YOUR-API-KEY> \
-d signature=<YOUR-REQUEST-SIGNATURE> \
-d collectionHash=<COLLECTION-HASH> \
-d background=color \
-d 'color=linear-gradient(180deg, ##1a1a2e 0%, ##16213e 100%)'

Response

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"
        }
    }
}