---
title: "Get folder by id"
url: "https://docs.signnow.com/docs/folder/operations/get-folder-by-id"
type: "endpoint"
section: "folder"
slug: "folder/operations/get-folder-by-id"
method: "GET"
path: "/folder/{folder_id}"
operation_id: "get-folder-by-id"
authorization: "bearer"
---

# Get folder by id

`GET /folder/{folder_id}`

This endpoint allows API users to retrieve the details of a folder, including its subfolders and the documents it contains. Use query parameters to filter, sort, and paginate the document list.

**Notes**

* `total_documents` is the total number of documents in the folder. The `documents` array contains only the page selected by `limit` and `offset`.
* To include document group templates, set `entity_type` to `dgt` or `all`. By default, a templates folder returns only templates.
* Each document's `document_group_template_info` lists the active document group templates that include it. For a document that isn't part of any document group template, the array is empty.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folder_id` | string | Yes | ID of the folder to return. |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filter-values` | string | No | Value for the filter set in `filters`. For `filters=signing-status`, one of: `signed`, `pending`, `waiting-for-me`, `waiting-for-others`, `unsent`, `expired`. For `filters=documents-created` or `filters=documents-updated`, a Unix timestamp: the response includes documents created or updated after this time. |
| `sortby` | string | No | Field to sort documents by. Possible values: `updated`, `created`, `document-name`. |
| `order` | string | No | Order of sorting. Can be used only with `sortby`. Possible values: `asc`, `desc`. |
| `offset` | integer | No | Number of documents to skip before the returned page starts. |
| `limit` | integer | No | Maximum number of documents to return. Max: `100`. |
| `entity_type` | string | No | Entities to include in the response. Possible values: `document-all` (documents, including documents in document groups), `document` (documents that aren't in document groups), `document-group` (document groups only), `template` (templates only), `dgt` (document group templates only), `all` (documents and document groups, or templates and document group templates in a templates folder). |
| `entity_labels` | string | No | Label to filter documents and document groups by. Possible values: `declined` (the invite was declined), `undelivered` (the invite email wasn't delivered). To use both, separate them with a comma: `declined,undelivered`. |
| `filters` | string | No | Filter to apply to the document list. Possible values: `signing-status`, `documents-created`, `documents-updated`. Use with `filter-values`. The `documents-created` and `documents-updated` filters exclude templates. |
| `include_documents_subfolders` | boolean | No | Whether to include subfolders to the response. Allowed values: `1`, `0`. |
| `with_team_documents` | boolean | No | Whether to display Team Documents folders. |
| `only_favorites` | boolean | No | Whether to show only favorite documents and document groups. |

## Responses

### 200

* Success
* With document group where user is a signer (+email group)
* With document group where user is the owner (+email group)
* With viewer field invites (+email group)
* With `entity_type=document-group` query
* With `entity_type=dgt` query

**Example** (`Success`)

```json
{
  "id": "1854d1191e5a862b8deb0badb1a8a29d9b23fad8",
  "name": "Documents",
  "shared": false,
  "created": "1409253077",
  "folders": [],
  "user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
  "documents": [
    {
      "id": "8580a5cc6f09e5a451f532ce357dd2b862d8bc89",
      "tags": [
        {
          "name": "fields",
          "type": "system"
        }
      ],
      "owner": "document_owner@email.com",
      "roles": [
        {
          "name": "Client",
          "unique_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "signing_order": "1"
        }
      ],
      "seals": [],
      "texts": [
        {
          "x": "281",
          "y": "195",
          "id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "data": "10/16/14",
          "font": "Arial",
          "size": "8",
          "email": "email_address@email.com",
          "created": "1413485018",
          "user_id": "ab410b7ff074fdaa7fec872244bf28dbb7e3e3d1",
          "line_height": "9.08",
          "page_number": "0"
        }
      ],
      "checks": [],
      "fields": [
        {
          "id": "ec103bdfd6fe29f2a719412c6d9dd13798afc6ef",
          "role": "Client",
          "type": "text",
          "role_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "field_id": "4006d215f9b56bc706a73b6467e4876c27a4f110",
          "fulfiller": "fulfiller@email.com",
          "element_id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "originator": "originator@email.com",
          "json_attributes": {
            "x": 281,
            "y": 195,
            "label": "Date",
            "width": 102,
            "height": 21,
            "required": true,
            "page_number": 0,
            "prefilled_text": ""
          },
          "field_request_id": "4006d215f9b56bc706a73b6467e4876c27a4f110",
          "template_field_id": "72de91bc89b622b6fcb561863803b3543013b33d",
          "field_request_canceled": null
        },
        {
          "id": "439c3ab0ed4f4f7cc2f5557f4deaceee54154cdf",
          "role": "Client",
          "type": "signature",
          "role_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "field_id": "4dfaa15dda85d21f6bfd74ccb2fa57fb100b57bb",
          "fulfiller": "fulfiller@email.com",
          "element_id": "5caeaa94ca9bfa52d59a7e1bfd0f434cf858f50c",
          "originator": "originator@email.com",
          "json_attributes": {
            "x": 91,
            "y": 186,
            "width": 122,
            "height": 34,
            "required": true,
            "page_number": 0
          },
          "field_request_id": "4dfaa15dda85d21f6bfd74ccb2fa57fb100b57bb",
          "template_field_id": "e95b1f221fc6bad34ebb9e6809ba3f2053dfd437",
          "field_request_canceled": null
        }
      ],
      "created": "1413307342",
      "inserts": [],
      "updated": "1413485018",
      "user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
      "requests": [
        {
          "email_sent_statuses": [
            {
              "status": "sent",
              "created_at": 1640108848,
              "last_reaction_at": 1640108848
            },
            {
              "status": "mail_open",
              "created_at": 1640108848,
              "last_reaction_at": 1640108849
            },
            {
              "status": "bounce",
              "created_at": 1640108848,
              "last_reaction_at": 1640108851
            },
            {
              "status": "mail_click",
              "created_at": 1640108848,
              "last_reaction_at": 1640108850
            }
          ]
        }
      ],
      "template": false,
      "parent_id": "1854d1191e5a862b8deb0badb1a8a29d9b23fad8",
      "thumbnail": {
        "large": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=large",
        "small": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=small",
        "medium": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=medium"
      },
      "page_count": "1",
      "signatures": [
        {
          "x": "91",
          "y": "195",
          "id": "5caeaa94ca9bfa52d59a7e1bfd0f434cf858f50c",
          "email": "email_address@email.com",
          "width": "122",
          "height": "25",
          "created": "1413485018",
          "user_id": "ab410b7ff074fdaa7fec872244bf28dbb7e3e3d1",
          "page_number": "0"
        }
      ],
      "attachments": [],
      "exported_to": [
        {
          "is_exported": false,
          "export_domain": "example.com",
          "exported_user_ids": []
        }
      ],
      "is_favorite": false,
      "version_time": "1413485018",
      "document_name": "Document 1",
      "entity_labels": [],
      "field_invites": [
        {
          "id": "738038bbedef2f94f7397869a099ca643dd5bd87",
          "role": "Client",
          "email": "user@email.com",
          "status": "fulfilled",
          "updated": "1413485018"
        },
        {
          "email_sent_statuses": [
            {
              "status": "sent",
              "created_at": 1640108848,
              "last_reaction_at": 1640108848
            },
            {
              "status": "mail_open",
              "created_at": 1640108848,
              "last_reaction_at": 1640108849
            },
            {
              "status": "bounce",
              "created_at": 1640108848,
              "last_reaction_at": 1640108851
            },
            {
              "status": "mail_click",
              "created_at": 1640108848,
              "last_reaction_at": 1640108850
            }
          ]
        }
      ],
      "notary_invites": [],
      "origin_user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
      "original_filename": "document_sample.pdf",
      "origin_document_id": "4a9b85af10913a404cf1f79192c46f4d2b15f76f",
      "enumeration_options": [],
      "document_group_template_info": [
        {
          "shared": 0,
          "own_as_merged": false,
          "document_group_template_id": "a1e6573b74a5f0327f0d9daa8421b6f7e6282e59",
          "document_group_template_name": "Onboarding package"
        }
      ]
    }
  ],
  "parent_id": "07d79fbf3d1308c5796c64a4147e4a4bc30c9170",
  "system_folder": true,
  "total_documents": 1
}
```

**Example** (`With declined document `)

```json
{
  "id": "1854d1191e5a862b8deb0badb1a8a29d9b23fad8",
  "name": "Documents",
  "shared": false,
  "created": "1409253077",
  "folders": [],
  "user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
  "documents": [
    {
      "id": "8580a5cc6f09e5a451f532ce357dd2b862d8bc89",
      "tags": [
        {
          "name": "fields",
          "type": "system"
        }
      ],
      "owner": "document_owner@email.com",
      "roles": [
        {
          "name": "Client",
          "unique_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "signing_order": "1"
        }
      ],
      "seals": [],
      "texts": [],
      "checks": [],
      "fields": [
        {
          "id": "ec103bdfd6fe29f2a719412c6d9dd13798afc6ef",
          "role": "Client",
          "type": "text",
          "role_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "field_id": "4006d215f9b56bc706a73b6467e4876c27a4f110",
          "fulfiller": "fulfiller@email.com",
          "element_id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "originator": "originator@email.com",
          "json_attributes": {
            "x": 281,
            "y": 195,
            "label": "Date",
            "width": 102,
            "height": 21,
            "required": true,
            "page_number": 0,
            "prefilled_text": ""
          },
          "field_request_id": "4006d215f9b56bc706a73b6467e4876c27a4f110",
          "template_field_id": "72de91bc89b622b6fcb561863803b3543013b33d",
          "field_request_canceled": null
        },
        {
          "id": "439c3ab0ed4f4f7cc2f5557f4deaceee54154cdf",
          "role": "Client",
          "type": "signature",
          "role_id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
          "field_id": "4dfaa15dda85d21f6bfd74ccb2fa57fb100b57bb",
          "fulfiller": "fulfiller@email.com",
          "element_id": "5caeaa94ca9bfa52d59a7e1bfd0f434cf858f50c",
          "originator": "originator@email.com",
          "json_attributes": {
            "x": 91,
            "y": 186,
            "width": 122,
            "height": 34,
            "required": true,
            "page_number": 0
          },
          "field_request_id": "4dfaa15dda85d21f6bfd74ccb2fa57fb100b57bb",
          "template_field_id": "e95b1f221fc6bad34ebb9e6809ba3f2053dfd437",
          "field_request_canceled": null
        }
      ],
      "created": "1413307342",
      "inserts": [],
      "updated": "1413485018",
      "user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
      "requests": [],
      "template": false,
      "parent_id": "1854d1191e5a862b8deb0badb1a8a29d9b23fad8",
      "thumbnail": {
        "large": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=large",
        "small": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=small",
        "medium": "http://example.com/document/8580a5cc6f09e5a451f532ce357dd2b862d8bc89/thumbnail?size=medium"
      },
      "page_count": "1",
      "signatures": [],
      "attachments": [],
      "exported_to": [
        {
          "is_exported": false,
          "export_domain": "example.com",
          "exported_user_ids": []
        }
      ],
      "is_favorite": false,
      "version_time": "1413485018",
      "document_name": "Document 1",
      "entity_labels": [
        {
          "updated": 1716320189,
          "is_system": true,
          "label_name": "declined"
        }
      ],
      "field_invites": [
        {
          "id": "738038bbedef2f94f7397869a099ca643dd5bd87",
          "role": "Client",
          "email": "user@email.com",
          "status": "fulfilled",
          "updated": "1413485018"
        },
        {
          "email_sent_statuses": [
            {
              "status": "sent",
              "created_at": 1640108848,
              "last_reaction_at": 1640108848
            },
            {
              "status": "mail_open",
              "created_at": 1640108848,
              "last_reaction_at": 1640108849
            },
            {
              "status": "bounce",
              "created_at": 1640108848,
              "last_reaction_at": 1640108851
            },
            {
              "status": "mail_click",
              "created_at": 1640108848,
              "last_reaction_at": 1640108850
            }
          ]
        }
      ],
      "notary_invites": [],
      "origin_user_id": "385859a93e9f216be2650cd8ef1a2fbd7da9c69c",
      "original_filename": "document_sample.pdf",
      "origin_document_id": "4a9b85af10913a404cf1f79192c46f4d2b15f76f",
      "enumeration_options": []
    }
  ],
  "parent_id": "07d79fbf3d1308c5796c64a4147e4a4bc30c9170",
  "system_folder": true,
  "total_documents": 1
}
```

**Example** (`With viewer field invites`)

```json
{
  "id": "a9ac43822ebc81e02672e6474166dc3f18d14c5b",
  "name": "Documents",
  "shared": false,
  "created": "1616586778",
  "folders": [],
  "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
  "documents": [
    {
      "id": "cd8a6caff1efcd5e3bcc0a5f8faedd7db5043625",
      "owner": "document-owner@email.com",
      "created": 1616586981,
      "invites": [
        {
          "email": "signer@email.com",
          "order": "1",
          "action": "sign",
          "status": "fulfilled",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": null
        },
        {
          "email": "manager@email.com",
          "order": "2",
          "action": "sign",
          "status": "fulfilled",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": null
        },
        {
          "order": "2",
          "action": "view",
          "status": "pending",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "email_group": {
            "id": "e7d703f9c028198c136a22bfa25b35b53d7791db",
            "name": "HR team"
          },
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": 1618210633
        }
      ],
      "updated": 1616586981,
      "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
      "documents": [
        {
          "id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "name": "sample",
          "roles": [
            "Signer 1",
            "Manager"
          ]
        }
      ],
      "invite_id": "ee92afd18b434160c2375ee9b765294db160e468",
      "entity_labels": [],
      "document_group_name": "Document Group 24-3-2021",
      "viewer_field_invites": [
        {
          "id": "ee92afd18b434160c2375ee9b765294db160e468",
          "email_group": {
            "id": "e7d703f9c028198c136a22bfa25b35b53d7791db",
            "name": "HR team"
          }
        }
      ]
    }
  ],
  "parent_id": "66b00b8e43e81fc4f2894d697407db5ec3fe5d1c",
  "system_folder": true,
  "total_documents": 1
}
```

**Example** (`With `entity_type=dgt` query`)

```json
{
  "id": "dafcf0486fde5d2a4845ff0f4f77ceed741da56c",
  "owner": "document-group-owner@email.com",
  "state": null,
  "pinned": false,
  "created": 1693474793,
  "invites": [],
  "updated": 1693474793,
  "user_id": "094a412b0cac4aa0bbbc525ed29e873fed70b184",
  "documents": [
    {
      "id": "108a4ae129611a50f772c1ae6ed626f1af3c959c",
      "name": "Sample image",
      "roles": [],
      "settings": null
    },
    {
      "id": "13c0f2f9617c4f61ca24fe14d3c9fe69700c58db",
      "name": "Sample image",
      "roles": [
        "Recipient 1"
      ],
      "settings": null
    }
  ],
  "invite_id": null,
  "parent_id": "f168bd45056f3a6a3105ffccca905ccd3d69e16e",
  "entity_type": "dgt",
  "is_favorite": false,
  "entity_labels": [],
  "recently_used": 1693474793,
  "sign_as_merged": false,
  "freeform_actions": [],
  "freeform_invite_id": null,
  "document_group_name": "Sample Document group",
  "originator_organization_settings": []
}
```

**Example** (`With `entity_type=document-group` query`)

```json
{
  "id": "4981d7a02a142db83bf2153d3dcec1ea78565a93",
  "owner": "document-group-owner@email.com",
  "state": "created",
  "pinned": false,
  "status": "created",
  "created": 1695288759,
  "invites": [],
  "updated": 1695288759,
  "user_id": "094a412b0cac4aa0bbbc525ed29e873fed70b184",
  "documents": [
    {
      "id": "2ca0843f880076aa6f228439b85465b77abd793d",
      "name": "Sample image",
      "roles": [],
      "settings": {
        "advanced_signing_flow": false
      }
    },
    {
      "id": "8299117e113fe353db1ec5e918f8c26797b59789",
      "name": "Sample image",
      "roles": [
        "Recipient 1"
      ],
      "settings": {
        "advanced_signing_flow": false
      }
    }
  ],
  "invite_id": null,
  "parent_id": "fb940c1ab23a5366c4d037b9cf184e1d4f004f5e",
  "entity_type": "document-group",
  "is_favorite": false,
  "entity_labels": [],
  "recently_used": 1695288759,
  "sign_as_merged": false,
  "freeform_actions": [],
  "freeform_invite_id": null,
  "document_group_name": "Sample Document group",
  "originator_organization_settings": []
}
```

**Example** (`With document group where user is a signer`)

```json
{
  "id": "a9ac43822ebc81e02672e6474166dc3f18d14c5b",
  "name": "Documents",
  "shared": false,
  "created": "1616586778",
  "folders": [],
  "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
  "documents": [
    {
      "id": "cd8a6caff1efcd5e3bcc0a5f8faedd7db5043625",
      "owner": "owner-email@email.com",
      "created": 1616586981,
      "updated": 1616586981,
      "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
      "documents": [
        {
          "id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "name": "sample",
          "roles": [
            "Signer 1",
            "Signer 2"
          ],
          "field_invites": [
            {
              "id": "e46b397eca8641fa99a46aec03482d2339d352c6",
              "email_group": {
                "id": "f6b94b6314a9be296e10844c9abb84fd35508a56",
                "name": "Contact group"
              }
            },
            {
              "id": "f0e05737aff830f8351c887c908b552ce5048f8e",
              "email_group": {
                "id": "c2825a468cab739f2773685c64547e4d0de2f25e",
                "name": "Contact group"
              }
            }
          ]
        }
      ],
      "invite_id": "ee92afd18b434160c2375ee9b765294db160e468",
      "entity_labels": [],
      "document_group_name": "Document Group 24-3-2021"
    }
  ],
  "parent_id": "66b00b8e43e81fc4f2894d697407db5ec3fe5d1c",
  "system_folder": true,
  "total_documents": 1
}
```

**Example** (`With document group invite where user is the owner`)

```json
{
  "id": "a9ac43822ebc81e02672e6474166dc3f18d14c5b",
  "name": "Documents",
  "shared": false,
  "created": "1616586778",
  "folders": [],
  "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
  "documents": [
    {
      "id": "cd8a6caff1efcd5e3bcc0a5f8faedd7db5043625",
      "owner": "document-owner@email.com",
      "created": 1616586981,
      "invites": [
        {
          "email": "signer@email.com",
          "order": "1",
          "action": "sign",
          "status": "fulfilled",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": null
        },
        {
          "email": "manager@email.com",
          "order": "2",
          "action": "sign",
          "status": "fulfilled",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": null
        },
        {
          "order": "2",
          "action": "view",
          "status": "pending",
          "document_id": "06d0f92bf2cf6b5749ec2fde9018fbcfa6b6c462",
          "email_group": {
            "id": "e7d703f9c028198c136a22bfa25b35b53d7791db",
            "name": "HR team"
          },
          "document_name": "Performance review",
          "authentication": null,
          "expiration_time": 1618210633
        }
      ],
      "updated": 1616586981,
      "user_id": "3032bc9359ae771a7cf1ef076c37593b8180cc10",
      "documents": [
        {
          "id": "d243243012aac357c45c19ee2c1998b6358bc457",
          "name": "sample",
          "roles": [
            "Signer 1",
            "Manager"
          ]
        }
      ],
      "invite_id": "ee92afd18b434160c2375ee9b765294db160e468",
      "entity_labels": [],
      "document_group_name": "Document Group 24-3-2021"
    }
  ],
  "parent_id": "66b00b8e43e81fc4f2894d697407db5ec3fe5d1c",
  "system_folder": true,
  "total_documents": 1
}
```

### 400

The folder does not exist or does not belong to the user.

**Example** (`Folder not found`)

```json
{
  "errors": [
    {
      "code": 65611,
      "message": "resource does not exist"
    }
  ]
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X GET \
  "https://api.signnow.com/folder/{folder_id}" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN"
```

---
*Full reference: https://docs.signnow.com/docs/folder/operations/get-folder-by-id*