# collection.getList

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

## Request parameters <a href="#request_params" id="request_params"></a>

| 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 *collection.getList*. If it is not specified, the request will return the error code "30 - Missing mandatory parameter".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| collectionStatus     | string | <p>The type of flipbook. Possible values are <em>public</em>, <em>editable</em> and <em>unlisted</em>.</p><p> Public flipbooks are listed on your public profile and in search results. They are publicly available to other users.</p><p> Editable flipbooks are not published. They must be published manually from the Flipsnack editor or updated using the <strong>collection.update</strong> method.</p><p> 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.</p><p><strong>Note:</strong> If you do not specify a flipbook status, the API will return all flipbooks within the specified range, regardless of their types.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 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 | <p>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 <strong>from</strong>) and the last record (parameter <strong>to</strong>).</p><p> By default, if you do not specify the <strong>from</strong> and <strong>to</strong> parameters, the API call returns the first 50 records.</p><p> Default: <em>0</em>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| to                   | number | <p>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 <strong>from</strong>) and the last record (parameter <strong>to</strong>).</p><p> By default, if you do not specify the <strong>from</strong> and <strong>to</strong> parameters, the API call returns the first 50 records.</p><p> Default: <em>50</em>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| orderBy              | string | <p>The field after which the returned list will be ordered. Possible values are <em>date\_published</em>, <em>date\_created</em> and <em>name</em>.</p><p> Default: <em>date\_published</em>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| orderMode            | string | <p>Specifies if the list will be ordered ascending or descending. Possible values are <em>asc</em> and <em>desc</em>.</p><p> Default: <em>desc</em>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| folder               | string | <p>The folder path where flipbooks are stored in your account. </p><ul><li>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.</li><li>The folder name is case insensitive. "My Folder" will be the same with "my folder".</li><li>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).</li><li>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.</li><li>The path must not include first or last slash character (/), excepting the case when you provide the slash (/) character alone as mentioned above.</li><li>Eg: <em>folder1</em></li></ul><p>You can specify a folder structure up to 3 levels. </p><ul><li>If a deeper folder is specified, it will be ignored.</li><li>in a structure, folder names must be separated with a slash character (/).</li><li>Eg: <em>folder1/folder2/folder3</em></li></ul><p>If the folder does not exists or there are no flipbooks in that folder you will receive 0 results.</p> |

## Response parameters <a href="#response_params" id="response_params"></a>

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| collectionsCount | string | <p>The total number of flipbooks that match the request. This number does not take into consideration the limits specified at the API call.</p><p> For example, your request could match 100 flipbooks, but it returns only the ones within the limits specified by <strong>from</strong> and <strong>to</strong> parameters.</p> |
| 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](#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 | <p>Possible values are:</p><ul><li><strong>public</strong>: The flipbook is published and accessible to the public. </li><li><strong>editable</strong>: The flipbook can be modified by the owner or authorized users. </li><li><strong>unlisted</strong>: The flipbook 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 flipbook 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 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 <a href="#error_codes" id="error_codes"></a>

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

## Examples <a href="#example" id="example"></a>

### &#x20;Request

{% tabs %}
{% tab title="cURL" %}

<pre class="language-bash"><code class="lang-bash"># GET
curl -X GET \
<strong>     -G \
</strong><strong>     https://api.flipsnack.com/v1/ \
</strong>     -d action=collection.getList \
     -d apiKey=&#x3C;YOUR-API-KEY> \
     -d collectionStatus=public \
     -d from=0 \
     -d to=2 \
     -d signature=&#x3C;YOUR-REQUEST-SIGNATURE>
</code></pre>

{% endtab %}

{% tab title="HTML" %}

```html
<form method="get" action="https://api.flipsnack.com/v1/">
    <input type="hidden" name="action" value="collection.getList">
    <input type="hidden" name="apiKey" value="<YOUR-API-KEY>">
    <input type="hidden" name="collectionStatus">
    <input type="hidden" name="from">
    <input type="hidden" name="to">
    <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": {
        "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 %}