List Folders

GET {{base_url}}/v1/folders

List Folders

This endpoint allows you to get a complete list of folders registered in the account, allowing you to apply filters, pagination, and sorting as needed.

Authentication

The previously obtained authentication token must be sent:

Authorization: Bearer {{access}}

Headers

To authorize access to the API, you must include the authentication token in the Authorization header using the Bearer scheme. Additionally, the Content-Type header must specify that the request body (if any) is sent in JSON format.

Parameter	Type	Description	Limits
`Authorization*`	string	Access token obtained during login, with the 'Bearer' prefix.	Required
`Content-Type`	string	Format of sent data.	'application/json'

Search Parameters

These parameters allow you to customize folder search results. You can filter by name, status, hierarchy, creation dates, and include additional data such as subfolders or the parent folder. All parameters are optional and can be combined as needed.

Parameter	Type	Description	Limits
`external_id`	string	Filter folders by their external identifier assigned by the client.	Optional
`parent_token`	string	Filter child folders of a specific parent folder.	Optional
`name`	string	Filter folders by name (partial search).	Optional
`active`	boolean	Filter active (true) or deleted (false) folders.	Optional
`sort_by`	string	Field to sort by (defaults to created_at).	Optional
`sort_order`	string	Result order: asc or desc.	Optional
`page`	integer	Current page of results (pagination).	Optional
`per_page`	integer	Number of results per page (defaults to 25).	Optional

Response Example

{
  "items": [
    {
      "external_id": "d4b7c8f1-27e4-4f92-b35a-5a3b81e0cf98",
      "token": "6a42e1b0-3f7c-45d2-8db4-12a7f3b52a61",
      "name": "Contrato Horizonte Azul",
      "description": "Acuerdo de colaboración para el suministro y soporte de infraestructura tecnológica",
      "document_count": 3,
      "signed_documents_count": 1,
      "in_progress_documents_count": 1,
      "not_started_documents_count": 1,
      "created_at": "2024-08-21T09:15:47.000000Z",
      "updated_at": "2024-09-05T16:42:30.000000Z",
      "deleted": false,
      "children": [],
      "parent": null
    }
  ],
  "pagination": {
    "total_items": 5,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 25,
    "first_page_url": "https://app.ejemplo.com/api/v1/folders?page=1",
    "last_page_url": "https://app.ejemplo.com/api/v1/folders?page=1"
  }
}

Fields Returned per Folder

Each item in the folder listing includes the full folder details, with the following fields available in the response. This data allows you to identify the folder, its status, its hierarchy (if applicable), and the number of documents it contains.

Nombre	Type	Description
`external_id`	string	External ID assigned by the client.
`token`	string	Unique internal token assigned by Firmeasy.
`name`	string	Folder name.
`description`	string	Folder description.
`document_count`	integer	Total number of documents.
`signed_documents_count`	integer	Signed documents.
`in_progress_documents_count`	integer	Documents in progress.
`not_started_documents_count`	integer	Documents not yet started.
`created_at`	datetime	Creation date.
`updated_at`	datetime	Last modification date.
`deleted`	boolean	Indicates if it is logically deleted.
`children`	array	List of subfolders.
`parent`	object/null	Parent folder (if it exists).

Pagination

The response always includes a pagination block that provides the complete status of the current query:

Nombre	Type	Description
`total_items`	integer	Total number of folders matching the applied filters.
`total_pages`	integer	Total number of pages available with the current `per_page` setting.
`current_page`	integer	Current page number.
`per_page`	integer	Number of records returned per page in this query.
`first_page_url`	string	Full URL of the first page of results.
`last_page_url`	string	Full URL of the last page of results.

Possible Errors

Code	Description
400	Invalid request (incorrect or missing parameters).
401	Unauthorized (invalid or missing token).
500	Unexpected internal error.