API Reference

PDFForge is a REST API for filling PDF forms, generating PDFs from HTML templates, and filling DOCX templates. All requests are made to:

https://api.pdfforge.dev/v1

The API accepts JSON request bodies (except file uploads which use multipart/form-data) and returns JSON responses. All timestamps are in ISO 8601 UTC format.

Key concepts:

• Templates — Reusable PDF forms, HTML/Handlebars templates, or DOCX templates stored in your account
• Documents — Generated PDFs or DOCX files created by filling a template with data
• API Keys — Bearer tokens used to authenticate every request (pk_live_ for production, pk_test_ for testing)

Every API request must include a valid API key in the Authorization header:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys use the format pk_live_ (production) or pk_test_ (testing) followed by 32 random characters. Keys are hashed with SHA-256 before storage — they are shown exactly once at creation time and can never be retrieved again.

You can create and manage API keys from the Dashboard or via the API Keys endpoints below.

Requests with a missing or invalid key receive a 401 Unauthorized response.

API keys come in two modes: Live (pk_live_) and Sandbox (pk_test_). Sandbox keys let you test your integration without affecting production quotas or triggering webhooks.

How sandbox mode differs from production:

Key behaviors:

• Sandbox keys access the same templates as live keys (shared data, no isolation)
• All three document types (PDF fill, HTML generate, DOCX fill) are watermarked
• Usage events are tracked separately with mode: "test" — they never count against your monthly quota
• The daily sandbox cap resets at midnight UTC
• Documents created in sandbox mode expire after 1 hour regardless of your plan

Creating sandbox keys:

Create a sandbox key from the Dashboard by selecting "Test" mode, or via the API:

POST /v1/api-keys
{ "name": "My Test Key", "mode": "test" }

Use sandbox keys exactly like live keys — just swap the Authorization header. The API automatically applies sandbox rules based on the key prefix.

Step 1 — Create an API key

Sign in to the Dashboard and create a new API key. Copy the raw key — you will not see it again.

Step 2 — Upload a template

Upload a PDF form, HTML/Handlebars template, or DOCX template via POST /v1/templates. The API detects fillable fields and template tags automatically.

Step 3 — Generate a document

Call POST /v1/documents/fill (for PDF forms and DOCX templates) or POST /v1/documents/generate (for HTML templates) with your template ID and data. You will receive a signed download URL in the response.

That's it. Three API calls to go from zero to a production document.

Webhooks notify your application when events occur in your PDFForge account. Each delivery includes an HMAC-SHA256 signature for verification.

Event types:

Signature verification:

Every webhook delivery includes an X-PDFForge-Signature header containing an HMAC-SHA256 signature of the request body, signed with your endpoint's secret:

X-PDFForge-Signature: sha256=<hex-digest>

Verify the signature in your handler to ensure the request came from PDFForge. The endpoint secret is returned when you create or retrieve a webhook endpoint.

Per-request webhooks:

In addition to global webhook endpoints, you can pass a webhook_url in the options of any fill or generate request. This fires a one-time, unsigned POST to your URL with the document response payload. Per-request webhooks are useful for async workflows where you want notification for a specific document.

{
  "template_id": "tpl_abc123",
  "data": { "name": "Jane" },
  "options": {
    "webhook_url": "https://your-app.com/hooks/pdfforge"
  }
}

Note: Webhooks are available on Pro plans and above. Sandbox (test) keys do not trigger webhooks.