Skip to content
FirmEasy
← Inicio

List Folders

GET
https://app.firmeasy.legal/api/v1/folders

List Folders

Section titled “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

Section titled “Authentication”

The previously obtained authentication token must be sent:

Authorization: Bearer {access}

Headers

Section titled “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.

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

Search Parameters

Section titled “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.

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

Response Example

Section titled “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

Section titled “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.

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

Section titled “Pagination”

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

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

Section titled “Possible Errors”
Code Description
400 Invalid request (incorrect or missing parameters).
401 Unauthorized (invalid or missing token).
500 Unexpected internal error.