List documents

This endpoint is cached by default with a TTL of 60 seconds.

GET https://api.zapsign.com.br/api/v1/docs/?page=1

This endpoint allows you to list all documents in your account. By default, results are returned in a paginated format.

---

URL Parameters (Query Params)

Parameter	Type	Description
page	integer	Page number for navigation (e.g., ?page=2).
status	string	Filter by status: pending (in progress), signed, or refused.
folder_path	string	Filter documents in a specific folder. Use / for the root.
deleted	boolean	true to list only deleted documents; false for active ones.
signer_email	string	Filter documents that contain a signer with this email.
created_from	string	Start date (format YYYY-MM-DD).
created_to	string	End date (format YYYY-MM-DD).
sort_order	string	Sort by creation date: asc (oldest first) or desc (newest first).
include_signers	boolean	(New) Use true, 1, or yes to include the signers array for each document.

---

Headers

Name	Type	Description
Authorization*	string	API token preceded by the word "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

---

Details on the include_signers parameter

When this parameter is enabled, the API will return a signers field within each document object, containing detailed information:

• Included Fields: Name, email, phone, authentication mode (auth_mode), digital certificate flag, interaction timestamps, signing URL, and signing order (if order is active).
• Signer Status: Exposed via a stable enum:

  • nao_abriu (has not opened)
  • abriu (opened)
  • assinou (signed)
  • recusou (refused)
  • expirou (expired)
  • cancelado (canceled)

    (Note: Document-level status takes precedence over individual status where applicable).

---

Important Notes

• JSON Consistency: Blank strings are normalized to null in the API response.
• Optimized Performance: The endpoint uses prefetch_related to avoid N+1 query issues when requesting signers, ensuring fast responses even for large lists.
• Temporary Links: The original_file and signed_file fields return links that expire in 60 minutes.
• Caching: This endpoint has a 60-second cache. If you have just created a document, it may take up to a minute to appear in this list.

---

Response Examples (JSON)

Example with include_signers = True

{
    "count": 120,
    "next": "https://api.zapsign.com.br/api/v1/docs/?page=2",
    "previous": null,
    "results": [
        {
            "token": "4f9e-a1b2-c3d4",
            "name": "Service Provision Contract",
            "status": "pending",
            "original_file": "https://s3.amazonaws.com/...",
            "signed_file": null,
            "created_at": "2024-03-25T14:30:00Z",
            "folder_path": "/",
            "signers": [
                {
                    "name": "João Silva",
                    "email": "[e-mail]",
                    "status": "abriu",
                    "auth_mode": "assinatura_tela",
                    "signing_url": "https://zapsign.com.br/sign/...",
                    "has_certificate": false,
                    "order": 1
                }
            ]
        }
    ]
}

Example without include_signers

[
    {
        "open_id": 1,
        "token": "7d23fcfa-d37e-44c6-a3c1-677a66383910",
        "status": "pending",
        "name": "Test Document",
        "original_file": "https://zapsign.s3.amazonaws.com/...",
        "signed_file": null,
        "created_at": "2020-04-16T02:43:31.500058Z",
        "last_update_at": "2020-04-16T02:43:31.500122Z"
    }
]

---

Pro Tip: Instead of polling the API multiple times a day, use our Webhooks. This saves computational capacity on both our servers and yours, and allows you to provide real-time feedback to your users.

Attention: Links returned in original_file and signed_file are temporary and last 60 minutes. If your system needs to store these links, we recommend downloading them to your own CDN or querying this endpoint whenever a fresh link is needed.