Skip to main content
Every PDF that Forme produces or processes is saved to the Documents archive. This gives you a searchable history of all renders, redactions, merges, and certifications — with download URLs, metadata filtering, and audit trails.

​
How Documents Are Created

ActionSourceAutomatic?
API render (POST /v1/render/:slug)generatedYes (opt out with save: false)
Manual upload in dashboarduploadedYes
Redaction (POST /v1/redact)redactedYes
Merge (POST /v1/merge)mergedYes
Certification (POST /v1/certify)certifiedYes

​
Controlling Save Behavior

By default, every sync render saves the PDF as a document. You can control this with two fields in the render request body:
  • save: false — skip saving entirely (useful for previews or ephemeral renders)
  • saveName: "Q1 Report" — custom document name instead of the default {slug}-{YYYY-MM-DD}

​
Metadata

Tag documents with your own key-value pairs for organization and retrieval: 
{
  "clientName": "Jane Smith",
  "metadata": {
    "customerId": "cust_123",
    "department": "billing"
  }
}
Developer metadata is merged with system metadata (renderTimeMs, templateSlug) on the document record.

​
Filtering

Query documents by metadata values using metadata.* query parameters: 
curl "https://api.formepdf.com/v1/documents?metadata.customerId=cust_123" \
  -H "Authorization: Bearer forme_sk_abc123..."
Multiple filters are ANDed together (maximum 5 per request). See Render API — Metadata for limits.

​
Retention

Documents are retained based on your plan:
PlanRetention
Free30 days
Pro90 days
Team1 year
BusinessUnlimited
After the retention period, documents and their stored PDFs are permanently deleted.

​
Storage

PDFs are stored in Cloudflare R2 (S3-compatible). The storageKey is server-side only and never exposed to the frontend.

​
Download URLs

Retrieve a document by ID to get a presigned download URL with 1-hour expiry: 
curl https://api.formepdf.com/v1/documents/clxyz... \
  -H "Authorization: Bearer forme_sk_abc123..."

{
  "data": {
    "id": "clxyz...",
    "name": "invoice-2024-01-15",
    "source": "generated",
    "downloadUrl": "https://..."
  }
}

​
Listing Documents

See Render API — Resources for the full listing API with pagination, source filtering, date ranges, and metadata queries.

​
Audit Trail

Every operation on a document is logged — who did what, when, and how (dashboard or API key). See Audit Trail for details.
Documents are a hosted API feature. Self-hosted instances have no storage layer — PDFs are returned directly and not persisted.