---
description: >-
  Returns information about a collection. The information contains configuration
  parameters for the player and the list of collection items.
---

# collection.getCollection

**Note:** Requests must be made to **https://api.flipsnack.com/v1**.

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-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 collection you wish to update. If you do not specify a collection 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 collection which was just created.

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| collectionHash        | string | The hash for the newly created collection. If the collection status is _editable_ the generated hash will be temporary. Once the collection is published, a new, final hash will be generated for it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| collectionTitle       | string | The title of the collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| collectionDescription | string | The description of the collection. It can be specified in the creation parameters or generated by the conversion system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| collectionStatus      | string | <p>Possible values are:</p><ul><li><strong>public</strong>: The collection is published and accessible to the public. </li><li><strong>editable</strong>: The collection can be modified by the owner or authorized users. </li><li><strong>unlisted</strong>: The collection is published but not publicly accessible without a direct link. </li><li><strong>processing</strong>: The flipbook is published but not yet complete. </li></ul><p>While in processing:</p><ul><li>the <strong>collection.update</strong> and <a href="api-method-collection.downloadhtml"><strong>collection.downloadHTML5</strong></a> endpoints are <strong>unavailable</strong>.</li><li>the public link for the flipbook may not yet be functional.</li></ul><p>Publishing a collection may take a few seconds. You can check the collectionStatus at regular intervals (e.g., every few seconds) using the <a href="api-method-collection.getcollection">collection.getCollection</a> method. Continue making requests to <a href="api-method-collection.getcollection"><strong>collection.getCollection</strong></a> until the collectionStatus has a value <strong>other than processing</strong>.</p> |
| coverImage            | string | The url of the collection's thumbnail image. This thumbnail is generated from the first page of the first collection item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| collectionPageCount   | number | The number of pages in the collection, for all the collection items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| createdDate           | date   | The date when the collection was created (not necessarily published).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| publishDate           | date   | The date when the collection was published.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| directLink            | string | The public link of the collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| flipbookPageCount     | number | <p>The number of pages of the collection item.<br><br>For collections created with the API, <strong>collectionPageCount</strong> and <strong>flipbookPageCount</strong> should have the same value.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| settings              | object | An object containing the [configuration parameters](../api-method-collection.create#configuration-parameters) of the collection, as set from the API call. [See the list below.](../api-method-collection.create#configuration-parameters)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| collectionItems       | array  | <p>The list of collection items belonging to the collection. In case of collections created using the API, the list contains a single item.<br><br>The <a href="../api-method-collection.create#collection-item-parameters">parameters of the collection item</a> are listed below.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### **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  | <p>The type of collection. Possible values are <em>public</em>, <em>editable</em> and <em>unlisted</em>.<br><br>Public collections are listed on your public profile and in search results. They are publicly available to other users.<br><br>Editable collections are not published. They must be published manually from the Flipsnack editor or updated using the <strong>collection.update</strong> method.<br><br>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.</p> |
| 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._                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### **Collection item parameters**

| Name                | Type   | Description                                                                                                                                                                   |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| flipbookHash        | string | The hash generated for the collection item.                                                                                                                                   |
| flipbookPageCount   | number | The number of pages of the collection 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 <a href="#error_codes" id="error_codes"></a>

For complete list of error codes and messages go to [api-status-codes](../api-status-codes "mention") section.



## Examples

### Request

{% tabs %}
{% tab title="cURL" %}
```bash
# GET     
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.getCollection \
     -d apiKey=<YOUR-API-KEY> \
     -d collectionHash=d3m0h45h \
     -d signature=<YOUR-REQUEST-SIGNATURE>
     
```
{% endtab %}

{% tab title="HTML" %}
```html
<form method="get" action="https://api.flipsnack.com/v1/">
    <input type="hidden" name="action" value="collection.getCollection">
    <input type="hidden" name="apiKey" value="<YOUR-API-KEY>">
    <input type="hidden" name="collectionHash">
    <input type="hidden" name="signature" value="<YOUR-REQUEST-SIGNATURE>">
    <button type="submit">Submit</button>
</form>
```
{% 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 %}
