API Reference

Complete reference for the TemplateFox API.

Base URL


https://api.pdftemplateapi.com

Authentication

All requests require an API key passed in the x-api-key header.


x-api-key: YOUR_API_KEY

Interactive Documentation

For interactive API testing:

Swagger Documentation - Interactive API explorer

Endpoints

POST /v1/pdf/create

Generate a PDF from a template.

Request

Field	Type	Required	Description
`template_id`	string	Yes	The 12-character template ID
`data`	object	Yes	Key-value pairs for template variables (see Data Binding)
`export_type`	string	No	`"url"` (default) or `"binary"`
`expiration`	number	No	URL expiration in seconds (default: 86400 = 24h, min: 60, max: 604800 = 7 days). Only applies to `"url"` export type.
`filename`	string	No	Custom filename for the PDF (without .pdf extension). Defaults to `"document"`.
`store_s3`	boolean	No	Upload to your configured S3 bucket instead of CDN. See S3 Storage Integration.
`s3_filepath`	string	No	Custom path prefix in your S3 bucket.
`s3_bucket`	string	No	Override the default bucket configured in your S3 integration.

Example Request


curl -X POST https://api.pdftemplateapi.com/v1/pdf/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "HMQywVpZxqAM",
    "data": {
      "customer_name": "John Doe",
      "invoice_number": "INV-001",
      "amount": "$1,234.56",
      "date": "2026-01-05"
    },
    "export_type": "url",
    "expiration": 86400
  }'

Response (export_type: url)


{
  "url": "https://storage.pdftemplateapi.com/generated/abc123.pdf",
  "filename": "document.pdf",
  "credits_remaining": 29,
  "expires_in": 86400
}

Field	Type	Description
`url`	string	Signed URL to the generated PDF
`filename`	string	Filename of the generated PDF
`credits_remaining`	number	Number of PDF generations remaining in your plan
`expires_in`	number	Seconds until the URL expires

Response (export_type: binary)

Returns the PDF file directly as application/pdf.

GET /v1/templates

List all templates for the authenticated user. Useful for integrations with no-code tools (Zapier, Make, n8n).

No credits consumed.

Example Request


curl https://api.pdftemplateapi.com/v1/templates \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "templates": [
    {
      "id": "HMQywVpZxqAM",
      "name": "Invoice Template",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:45:00Z"
    },
    {
      "id": "xK9mNpQrStUv",
      "name": "Packing Slip",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    }
  ]
}

GET /v1/templates/{template_id}/fields

Get the dynamic fields (variables) for a template. Useful for building dynamic forms in integrations.

No credits consumed.

Example Request


curl https://api.pdftemplateapi.com/v1/templates/HMQywVpZxqAM/fields \
  -H "x-api-key: YOUR_API_KEY"

Response


[
  {
    "key": "customer_name",
    "label": "customer_name",
    "type": "string",
    "required": false,
    "helpText": "e.g. John Doe"
  },
  {
    "key": "items",
    "label": "items",
    "type": "string",
    "required": false,
    "helpText": "JSON array, e.g. [{\"name\": \"Product\", \"price\": 99}]"
  }
]

Field	Type	Description
`key`	string	Field identifier to use in the `data` object
`label`	string	Human-readable label
`type`	string	Field type: `string`, `integer`, `number`, `boolean`
`required`	boolean	Whether the field is required
`helpText`	string	Help text with example value

GET /v1/account

Get account information including remaining credits.

No credits consumed.

Example Request


curl https://api.pdftemplateapi.com/v1/account \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "credits": 142,
  "email": "user@example.com"
}

GET /v1/account/transactions

List transaction history with pagination.

No credits consumed.

Query Parameters

Parameter	Type	Default	Description
`limit`	number	300	Number of records to return (1-1000)
`offset`	number	0	Number of records to skip

Example Request


curl "https://api.pdftemplateapi.com/v1/account/transactions?limit=10&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "transactions": [
    {
      "transaction_ref": "550e8400-e29b-41d4-a716-446655440000",
      "transaction_type": "PDFGEN",
      "template_id": "HMQywVpZxqAM",
      "exec_tm": 1250,
      "credits": 1,
      "created_at": "2026-01-20T14:30:00Z"
    },
    {
      "transaction_ref": "550e8400-e29b-41d4-a716-446655440001",
      "transaction_type": "PURCHASE",
      "template_id": null,
      "exec_tm": null,
      "credits": -100,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0
}

Transaction Type	Description
`PDFGEN`	PDF generation (credits consumed)
`PURCHASE`	Credit purchase (credits added)
`REFUND`	Credit refund on failed generation
`BONUS`	Bonus credits

Note: Positive credits = consumed, negative credits = added.

S3 Storage Integration

Configure your own S3-compatible storage to store generated PDFs directly in your bucket.

GET /v1/integrations/s3

Get current S3 storage configuration (secret key is masked).

Example Request


curl https://api.pdftemplateapi.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

Response (configured)


{
  "configured": true,
  "endpoint_url": "https://s3.amazonaws.com",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "bucket_name": "my-pdf-bucket",
  "default_prefix": "invoices/"
}

Response (not configured)


{
  "configured": false
}

POST /v1/integrations/s3

Save or update S3 storage configuration.

Request

Field	Type	Required	Description
`endpoint_url`	string	Yes	S3-compatible endpoint URL (must start with `https://`)
`access_key_id`	string	Yes	Access key ID (16-128 characters)
`secret_access_key`	string	No	Secret access key (only required on first setup or to update)
`bucket_name`	string	Yes	Bucket name (3-63 characters, lowercase)
`default_prefix`	string	No	Default path prefix for uploaded files

Example Request


curl -X POST https://api.pdftemplateapi.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://s3.amazonaws.com",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "bucket_name": "my-pdf-bucket",
    "default_prefix": "invoices/"
  }'

Response


{
  "success": true
}

DELETE /v1/integrations/s3

Delete S3 storage configuration.

Example Request


curl -X DELETE https://api.pdftemplateapi.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "success": true
}

POST /v1/integrations/s3/test

Test S3 connection with stored credentials.

Example Request


curl -X POST https://api.pdftemplateapi.com/v1/integrations/s3/test \
  -H "x-api-key: YOUR_API_KEY"

Response (success)


{
  "success": true
}

Response (failure)


{
  "detail": "Connection test failed: Access Denied"
}

Using S3 Storage with PDF Generation

Once configured, use the store_s3 parameter in /v1/pdf/create:

Request

Field	Type	Required	Description
`store_s3`	boolean	No	Set to `true` to upload to your S3 bucket
`s3_filepath`	string	No	Custom path prefix (overrides default_prefix)
`s3_bucket`	string	No	Override the configured bucket

Example Request


curl -X POST https://api.pdftemplateapi.com/v1/pdf/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "HMQywVpZxqAM",
    "data": {"customer_name": "John Doe"},
    "store_s3": true,
    "filename": "invoice-001",
    "s3_filepath": "2026/01/"
  }'

Response


{
  "s3_bucket": "my-pdf-bucket",
  "s3_key": "2026/01/invoice-001.pdf",
  "filename": "invoice-001.pdf",
  "credits_remaining": 99
}

Error Codes

Status	Code	Description
400	`INVALID_REQUEST`	Missing or invalid request parameters
401	`UNAUTHORIZED`	Invalid or missing API key
402	`INSUFFICIENT_CREDITS`	No credits remaining
403	`FORBIDDEN`	Access denied (not your template)
404	`TEMPLATE_NOT_FOUND`	Template ID not found
500	`INTERNAL_ERROR`	Server error

Error Response Format


{
  "error": "TEMPLATE_NOT_FOUND",
  "message": "Template with ID 'xyz' not found"
}

Rate Limits

Plan	Requests/min	Requests/day
Free	10	100
Pro	60	10,000
Enterprise	Custom	Custom

Rate limit headers are included in every response:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704384000