Python SDK & REST Examples — TemplateFox

Two ways to use the TemplateFox API from Python:

SDK (templatefox) — typed client auto-generated from our OpenAPI spec. Recommended.
REST — requests or httpx. Useful for minimal dependencies or endpoints not yet in the SDK.

Every example on this page shows both side-by-side.

Installation

pip install templatefox
# or
poetry add templatefox
# or
uv add templatefox

For the REST variant, just pip install requests.

Configuration

Set your API key once and reuse the client.

import os
from templatefox import ApiClient, Configuration
from templatefox.api import PDFApi

config = Configuration()
config.api_key["ApiKeyAuth"] = os.environ["TEMPLATEFOX_API_KEY"]

client = ApiClient(config)
api = PDFApi(client)

import os
import requests

BASE_URL = "https://api.templatefox.com"
HEADERS = {"x-api-key": os.environ["TEMPLATEFOX_API_KEY"]}

Generate a PDF

The minimum required fields are template_id and data. Everything else has a sensible default.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
          "amount": "$1,234.56",
      },
  )
)

print(response.url)                # signed URL valid 24h
print(response.credits_remaining)  # credits left on the team

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
          "amount": "$1,234.56",
      },
  },
).json()

print(response["url"])

See Create PDF for every supported parameter.

Save the PDF to a file

import urllib.request
from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"customer_name": "Jane Doe"},
  )
)

urllib.request.urlretrieve(response.url, "invoice.pdf")

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"customer_name": "Jane Doe"},
      "export_type": "binary",   # PDF bytes returned directly
  },
)

with open("invoice.pdf", "wb") as f:
  f.write(response.content)

With the SDK you fetch the signed URL then save. With REST you can also ask for export_type="binary" to stream the bytes directly.

Upload straight to your S3 bucket

Configure your S3 integration once in the dashboard, then pass store_s3=True on any call.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"invoice_number": "INV-001"},
      filename="invoice-001",           # no extension, .pdf appended
      store_s3=True,                     # upload to your configured bucket
      s3_filepath="invoices/2026/04/",  # key prefix (optional)
      # s3_bucket="custom-bucket",      # override bucket from integration
  )
)

print(response.s3_bucket, response.s3_key)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"invoice_number": "INV-001"},
      "filename": "invoice-001",           # no extension
      "store_s3": True,                     # upload to your configured bucket
      "s3_filepath": "invoices/2026/04/",  # key prefix (optional)
      # "s3_bucket": "custom-bucket",      # override bucket from integration
  },
).json()

print(response["s3_bucket"], response["s3_key"])

PDF/A compliance

For archival/legal use-cases, request a PDF/A variant.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"customer_name": "John Doe"},
      pdf_variant="pdf/a-2b",   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
  )
)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"customer_name": "John Doe"},
      "pdf_variant": "pdf/a-2b",   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
  },
)

Async generation with webhooks

For large documents or batch jobs, use the async endpoint and receive a webhook when the PDF is ready. See Create PDF (Async) for the full flow.

response = requests.post(
  f"{BASE_URL}/v1/pdf/create-async",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"invoice_number": "INV-001"},
      "webhook_url": "https://example.com/webhooks/pdf",
      "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",  # HMAC-SHA256 signing
  },
).json()

job_id = response["job_id"]
# Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

Async endpoints (create-pdf-async, jobs) are not yet exposed in the SDK — use requests directly until then.

Error handling

from templatefox.exceptions import ApiException
from templatefox.models import CreatePdfRequest

try:
  response = api.create_pdf(
      CreatePdfRequest(template_id="INVALID_ID", data={})
  )
except ApiException as e:
  print(e.status, e.body)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={"template_id": "INVALID_ID", "data": {}},
)

if not response.ok:
  print(response.status_code, response.json().get("detail"))

See Error codes for the full list.

Available SDK methods

Class	Method	Endpoint
`PDFApi`	`create_pdf`	`POST /v1/pdf/create`
`TemplatesApi`	`list_templates`	`GET /v1/templates`
`TemplatesApi`	`get_template_fields`	`GET /v1/templates/{id}/fields`
`AccountApi`	`get_account`	`GET /v1/account`
`AccountApi`	`list_transactions`	`GET /v1/account/transactions`
`IntegrationsApi`	`save_s3_config`	`POST /v1/integrations/s3`
`IntegrationsApi`	`get_s3_config`	`GET /v1/integrations/s3`
`IntegrationsApi`	`delete_s3_config`	`DELETE /v1/integrations/s3`
`IntegrationsApi`	`test_s3_connection`	`POST /v1/integrations/s3/test`

All REST endpoints are documented in the API Reference.

Next steps

Create PDF — every parameter in detail
Create PDF Async — webhooks + polling
GitHub repository — source, changelog, issues
Postman collection — test endpoints interactively