Create Folder

POST {{base_url}}/v1/folders

curl -X POST {{base_url}}/v1/folders \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Employment Contracts 2026",
  "external_id": "CL-2026-001",
  "description": "Documents for the labor area"
}'

Sin ejecutar·latencia ~ 412 ms

Demo pública · no guarda datos · firma con sandbox PKI

Create Folder

This endpoint allows you to create a new folder within your account. Folders are fundamental organizational structures that let you group documents by categories, departments, or any business logic defined by your system.

Authorization

To consume this resource, you must include your access token in the request header using the Bearer scheme.

Parameter	Type	Description	Limits
`Authorization*`	string	Access token obtained during the login process, preceded by the word 'Bearer'.	Required
`Content-Type*`	string	Specifies the format of the request body.	application/json

Request Parameters

Required Fields

Fields marked with an asterisk (*) are required and must be provided in the request. Other fields are optional.

Below are the parameters you can send in the body of your request in JSON format.

Parameter	Type	Description	Limits
`name*`	string	Display name that the folder will have on the platform.	Max: 100 characters
`external_id`	string	Custom identifier. Useful for linking the created folder with the internal ID of your own system's database.	Max: 255 characters
`description`	string	Additional details or notes about the folder's purpose.	Between 5 and 255 characters
`parent_id`	string	Token (UUID) of another existing folder. Use this field only if you want the new folder to be created as a subfolder.	Valid UUID format

Implementation Examples

Here are ready-to-copy examples to test the integration immediately.

cURL

curl -X POST {{base_url}}/v1/folders \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contratos Laborales 2026",
    "external_id": "CL-2026-001",
    "description": "Carpeta destinada a los nuevos ingresos de este año."
  }'

Node.js (Fetch)

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer TU_TOKEN_AQUI");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "name": "Contratos Laborales 2026",
  "external_id": "CL-2026-001",
  "description": "Carpeta destinada a los nuevos ingresos de este año."
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("{{base_url}}/v1/folders", requestOptions)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response Structure

Once the request is processed, the API will return a JSON object with the details of the newly created folder along with its unique token.

Successful Response (200 OK)

{
  "external_id": "CL-2026-001",
  "token": "8d17c3b4-71f0-4c1a-bf54-2a94d60a23a1",
  "name": "Contratos Laborales 2026",
  "description": "Carpeta destinada a los nuevos ingresos de este año.",
  "document_count": 0,
  "signed_documents_count": 0,
  "in_progress_documents_count": 0,
  "not_started_documents_count": 0,
  "created_at": "2026-06-15T10:30:00.000000Z",
  "updated_at": "2026-06-15T10:30:00.000000Z",
  "deleted": false,
  "parent": null
}

Nombre	Type	Description
`token`	string	Unique and definitive identifier generated by Firmeasy. Save it in your database, as you will need it for future operations (such as adding documents to it).
`external_id`	string	The same ID you sent in the original request for your system's validation.
`name`	string	Name assigned to the folder.
`document_count`	integer	Total documents stored (will start at 0).
`created_at`	datetime	Exact creation date and time in UTC ISO 8601 format.

Integration Considerations

Token Storage: It is crucial that you store the returned token in your database, as it is the main key to interact with this folder in the future.
Hierarchies: You can create subfolders by sending the parent folder’s token in the parent_id parameter.

Status Codes

Code	Status	Description
`200`	OK	The folder was created successfully.
`400`	Bad Request	Invalid syntax or missing required field `name`.
`401`	Unauthorized	The Bearer token was not sent, has expired, or is incorrect.
`409`	Conflict	A folder with that same `external_id` already exists in your account.
`500`	Server Error	Internal failure in Firmeasy’s servers.