> For the complete documentation index, see [llms.txt](https://developers.flipsnack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.flipsnack.com/api-reference/api-method-collection.update.md). # collection.update **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.md) 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.md) 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.md) 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 %}