Skip to content

Get Document

GET {{base_url}}/v1/documents/{{token}}

Get Document

Gets the full detail, signature status, and links of a specific document (envelope) by its identifier token.

Authentication

Parameter	Type	Description	Limits
`Authorization*`	string	Access token obtained during the login process, with the 'Bearer' prefix.	Required

Path Parameters

Parameter	Type	Description	Limits
`token*`	string	Unique identifier (UUID) of the document returned when it was created.	Required

Query Parameters

Parameter	Type	Description	Limits
`include[]`	string[]	Allows expanding object relationships. Use 'children' to include the full attachments array (extra_docs). Ex: ?include[]=children	Optional

Successful Response (200 OK)

Returns the Document object with its current status. If ?include[]=children is included in the query, the extra_docs array will be populated with the attachment details.

{
  "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": "{{base_url}}/v1/files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "{{base_url}}/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": [
    {
      "token": "anexo-token",
      "name": "Anexo 1 - Tarifario 2026.pdf",
      "original_file": "{{base_url}}/v1/files/.../?intent=view&...",
      "signed_file": null,
      "original_download_file": "{{base_url}}/v1/files/.../?intent=download&...",
      "signed_download_file": null,
      "uploaded_by": { "email": "[email protected]" }
    }
  ],
  "extra_docs_count": 1,
  "signers": [
    {
      "external_id": null,
      "token": "signer-api-id",
      "status": "pending",
      "rejection_reason": null,
      "order": 1,
      "name": "Jane Doe",
      "email": "[email protected]",
      "phone": "900000001",
      "country_code": "+51",
      "document_type": "dni",
      "document_number": "900000003",
      "role": "signer",
      "identifier": "...",
      "link": "https://app.firmeasy.legal/...",
      "signed_at_hour": null,
      "signed_at": null,
      "position_x": null,
      "position_y": null,
      "page": null,
      "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
        }
      ],
      "standard_flow": [
        {
          "state": "pending",
          "flow_name": "Firma Digital Local",
          "flow_key": "digital_certificate_local"
        }
      ],
      "advanced_flow": [],
      "created_through": "api",
      "send_automatic_invitations": true,
      "send_signed_document_by_whatsapp": false,
      "geo_latitude": null,
      "geo_longitude": null,
      "lang": "es",
      "created_at": "2026-06-23T10:00:00.000000Z",
      "updated_at": "2026-06-23T10:00:00.000000Z"
    }
  ],
  "tracking": [],
  "created_through": "api",
  "reminder_every_n_days": 0,
  "send_automatic_invitations": true,
  "send_signed_document_by_whatsapp": false,
  "is_rejection_allowed": true,
  "is_signature_order_active": false,
  "redirect_link": null,
  "observers": [],
  "metadata": { "order_id": "12345" },
  "created_at": "2026-06-23T10:00:00.000000Z",
  "updated_at": "2026-06-23T10:00:00.000000Z"
}

Nombre	Type	Description
`token`	string	Unique envelope identifier generated by FirmEasy.
`external_id`	string	External ID assigned by the integrator when creating the document.
`name`	string	Normalized document name (in UPPERCASE with '.pdf' extension).
`status`	string	Current envelope status. Possible values: 'pending', 'signed', 'rejected'.
`original_file`	string	Signed URL to view the original PDF in the browser. Expires in 60 minutes.
`signed_file`	string	URL of the signed document. Null while the envelope is not fully signed.
`original_download_file`	string	Signed URL to download the original PDF directly. Expires in 60 minutes.
`signed_download_file`	string	URL to download the signed document. Null until all signatures are complete.
`signatures_made`	integer	Number of signatures stamped so far.
`extra_docs_count`	integer	Number of attached documents included in the envelope.
`extra_docs`	array	List of attachments with their tokens and download URLs. It is populated only if ?include[]=children is sent in the query.
`signers`	array	List of signers with their status, signature link, configured flows, and signature placements.
`tracking`	array	Envelope event history.
`metadata`	object	Free JSON key-value object with custom metadata sent when creating the envelope.
`created_at`	datetime	Exact date and time of envelope creation in UTC ISO 8601 format.
`updated_at`	datetime	Date and time of the last envelope modification in UTC ISO 8601 format.

Where do `extra_docs` and `extra_docs_count` appear?

Endpoint / Context	`extra_docs`	`extra_docs_count`
`POST /v1/documents` (201)	always	—
Webhooks `document_created` / `document_completed`	always	—
`GET /v1/documents/{{token}}`	with `?include[]=children`	—
`GET /v1/documents` (list)	with `?include[]=children`	always

extra_docs is an array of attachments with their tokens, names and download URLs. extra_docs_count is an integer counter always included in listings to know the attachment count without expanding the relationship.

Possible Errors

Code	Status	Description
`401`	Unauthorized	The authentication token is invalid, expired, or was not sent.
`404`	Not Found	The document `token` does not exist or does not belong to the associated organization.