Skip to content
FirmEasy
← Inicio

List Documents

GET
https://api.firmeasy.legal/api/v1/documents

List Documents

Section titled “List Documents”

Returns a paginated list of all documents (envelopes) created by the organization. By default, each item includes the attachment count; if you need to retrieve the full detail of attachments, you can expand the relationship in the query.

Authentication

Section titled “Authentication”
Authorization
string
Bearer authentication token.
Limits:Required (Bearer <token>)

Query Parameters

Section titled “Query Parameters”
include[]
string[]
Allows expanding object relationships. Use children to populate the full attachments array (extra_docs). Ex: ?include[]=children
Limits:Optional

Successful Response (200 OK)

Section titled “Successful Response (200 OK)”

Returns a collection of Document objects. In this example, the first element shows the structure when expansion is not requested (attachment values are null) and the second shows an element with the expanded relationship.

[
  {
    "external_id": "ERP-123",
    "token": "abcdef01-...",
    "name": "CONTRATO DE PRESTACIÓN DE SERVICIOS N°9.pdf",
    "folder": { "token": "uuid", "name": "Carpeta" },
    "status": "pending",
    "lang": "es",
    "size": 245100,
    "original_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "signed_file": null,
    "original_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signed_download_file": null,
    "signatures_made": 0,
    "signature_deadline": "2026-12-31T23:59:59.000Z",
    "created_by": { "email": "[email protected]" },
    "extra_docs": null,
    "extra_docs_count": 2,
    "signers": [
      {
        "external_id": null,
        "token": "signer-api-id",
        "status": "pending",
        "name": "Jane Doe",
        "email": "[email protected]",
        "role": "signer",
        "link": "[https://app.firmeasy.legal/](https://app.firmeasy.legal/)...",
        "placements": [
          {
            "document_ref": "main",
            "type": "signature",
            "page_number": 1,
            "relative_position_left": 36.5,
            "relative_position_top": 39.25,
            "relative_size_width": 25,
            "relative_size_height": 8
          }
        ]
      }
    ],
    "created_through": "api",
    "metadata": { "order_id": "12345" },
    "created_at": "2026-06-23T10:00:00.000000Z",
    "updated_at": "2026-06-23T10:00:00.000000Z"
  },
  {
    "external_id": "ERP-124",
    "token": "789fgh02-...",
    "name": "ADENDA DE CONTRATO DE LOCACIÓN.pdf",
    "folder": null,
    "status": "signed",
    "lang": "es",
    "size": 124000,
    "original_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "signed_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=](https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=)...",
    "original_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signed_download_file": "[https://api.firmeasy.legal/api/v1/files/...?intent=download](https://api.firmeasy.legal/api/v1/files/...?intent=download)&...",
    "signatures_made": 1,
    "signature_deadline": "2026-08-15T18:00:00.000Z",
    "created_by": { "email": "[email protected]" },
    "extra_docs": [
      {
        "token": "anexo-token-99",
        "name": "Anexo de Especificaciones Técnicas.pdf",
        "original_file": "[https://api.firmeasy.legal/api/v1/files/.../?intent=view](https://api.firmeasy.legal/api/v1/files/.../?intent=view)&...",
        "signed_file": null,
        "original_download_file": "[https://api.firmeasy.legal/api/v1/files/.../?intent=download](https://api.firmeasy.legal/api/v1/files/.../?intent=download)&...",
        "signed_download_file": null,
        "uploaded_by": { "email": "[email protected]" }
      }
    ],
    "extra_docs_count": 1,
    "signers": [
      {
        "external_id": null,
        "token": "signer-api-2",
        "status": "signed",
        "name": "James Smith",
        "email": "[email protected]",
        "role": "signer",
        "link": "[https://app.firmeasy.legal/](https://app.firmeasy.legal/)...",
        "placements": [
          {
            "document_ref": "main",
            "type": "signature",
            "page_number": 2,
            "relative_position_left": 10.0,
            "relative_position_top": 45.0,
            "relative_size_width": 20,
            "relative_size_height": 10
          }
        ]
      }
    ],
    "created_through": "api",
    "metadata": {},
    "created_at": "2026-06-24T08:30:00.000000Z",
    "updated_at": "2026-06-24T09:15:00.000000Z"
  }
]
external_id
string
Your external ID (pass-through).
token
string (UUID)
Document identifier (use it in other endpoints).
name
string
Envelope name (normalized to UPPERCASE + .pdf).
folder
object
Destination folder containing token and name.
status
string
Document status: pending · signed · rejected.
lang
string
Interface language: es · en · pt.
size
integer
File size in bytes.
original_file
string (URL)
Temporary viewing URL for the original file (expires in 60 min).
signed_file
string (URL)
Temporary viewing URL for the signed file (null until >=1 signature, expires in 60 min).
original_download_file
string (URL)
Temporary download URL for the original file with filename (expires in 60 min).
signed_download_file
string (URL)
Temporary download URL for the signed file (expires in 60 min).
signatures_made
integer
Number of signatures applied.
signature_deadline
string (ISO8601)
Signature deadline date in Y-m-d\TH:i:s.v\Z format.
created_by
object
Document creator containing the email.
extra_docs
array
Array of attachments (only if the envelope has them). Always present in create and webhooks or expanded via include.
extra_docs_count
integer
Number of attachments. Always present in the listing; cheap signal without fetching the array.
signers
array
Collection of envelope signers with their respective flows and placements.
tracking
array
Document audit and tracking events.
created_through
string
Creation channel: api · web.
reminder_every_n_days
integer
Automatic reminder frequency (0-30 days).
send_automatic_invitations
boolean
Indicates whether automatic invitations are sent upon creation.
send_signed_document_by_whatsapp
boolean
Indicates whether the signed document is sent via WhatsApp.
is_rejection_allowed
boolean
Allow document rejection by signers.
is_signature_order_active
boolean
Indicates whether the configured signature order is strictly enforced.
redirect_link
string
Post-signature redirect URL.
observers
array
Observer emails (read-only).
metadata
object
Pass-through of free-form data in key-value format.
created_at
string (ISO8601)
Record creation date.
updated_at
string (ISO8601)
Last record update date.

Common Error Responses

Section titled “Common Error Responses”
Code Status Description
401 Unauthorized The authentication token is invalid, expired, or was not sent.
422 Unprocessable Entity The sorting parameters, filters, or relationships requested in include are not valid.