Java SDK & REST Examples — TemplateFox

Two ways to use the TemplateFox API from Java:

SDK (io.github.templatefoxpdf:sdk) — typed client auto-generated from our OpenAPI spec. Recommended.
REST — the JDK 11+ java.net.http client. Useful for minimal dependencies.

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

Installation

Maven

<dependency>
    <groupId>io.github.templatefoxpdf</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'io.github.templatefoxpdf:sdk:1.0.0'

The REST variant only needs JDK 11+ (no dependency).

Configuration

Set your API key once and reuse the client.

import com.templatefox.sdk.ApiClient;
import com.templatefox.sdk.api.PDFApi;

var client = new ApiClient();
client.setApiKey(System.getenv("TEMPLATEFOX_API_KEY"));

var api = new PDFApi(client);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

static final String BASE_URL = "https://api.templatefox.com";
static final String API_KEY  = System.getenv("TEMPLATEFOX_API_KEY");
static final HttpClient CLIENT = HttpClient.newHttpClient();

Generate a PDF

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

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("customer_name",  "John Doe")
  .putDataItem("invoice_number", "INV-001")
  .putDataItem("amount",         "$1,234.56");

var response = api.createPdf(request);

System.out.println(response.getUrl());              // signed URL valid 24h
System.out.println(response.getCreditsRemaining()); // credits left on the team

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": {
  "customer_name":  "John Doe",
  "invoice_number": "INV-001",
  "amount":         "$1,234.56"
}
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

See Create PDF for every supported parameter.

Save the PDF to a file

import java.io.*;
import java.net.URL;

var response = api.createPdf(request);

try (var in  = new URL(response.getUrl()).openStream();
   var out = new FileOutputStream("invoice.pdf")) {
  in.transferTo(out);
}

import java.nio.file.*;

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "customer_name": "Jane Doe" },
"export_type": "binary"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofFile(Paths.get("invoice.pdf")));

Upload straight to your S3 bucket

Configure your S3 integration once in the dashboard, then pass storeS3(true) on any call.

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("invoice_number", "INV-001")
  .filename("invoice-001")            // no extension, .pdf appended
  .storeS3(true)                      // upload to your configured bucket
  .s3Filepath("invoices/2026/04/");   // key prefix (optional)
  // .s3Bucket("custom-bucket")       // override bucket from integration

var response = api.createPdf(request);
System.out.println(response.getS3Bucket() + "/" + response.getS3Key());

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "invoice_number": "INV-001" },
"filename":    "invoice-001",
"store_s3":    true,
"s3_filepath": "invoices/2026/04/"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

PDF/A compliance

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

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("customer_name", "John Doe")
  .pdfVariant("pdf/a-2b");  // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"

var response = api.createPdf(request);

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "customer_name": "John Doe" },
"pdf_variant": "pdf/a-2b"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

Async generation with webhooks

For large documents or batch jobs, use the async endpoint. See Create PDF (Async) for the full flow.

var body = """
{
"template_id":    "YOUR_TEMPLATE_ID",
"data":           { "invoice_number": "INV-001" },
"webhook_url":    "https://example.com/webhooks/pdf",
"webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create-async"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
// Parse job_id, then 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 java.net.http directly until then.

Error handling

import com.templatefox.sdk.ApiException;

try {
  var response = api.createPdf(request);
} catch (ApiException e) {
  System.err.println("status=" + e.getCode() + " body=" + e.getResponseBody());
}

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() >= 400) {
  System.err.println("status=" + response.statusCode() + " body=" + response.body());
}

See Error codes for the full list.

Available SDK methods

Class	Method	Endpoint
`PDFApi`	`createPdf`	`POST /v1/pdf/create`
`TemplatesApi`	`listTemplates`	`GET /v1/templates`
`TemplatesApi`	`getTemplateFields`	`GET /v1/templates/{id}/fields`
`AccountApi`	`getAccount`	`GET /v1/account`
`AccountApi`	`listTransactions`	`GET /v1/account/transactions`
`IntegrationsApi`	`saveS3Config`	`POST /v1/integrations/s3`
`IntegrationsApi`	`getS3Config`	`GET /v1/integrations/s3`
`IntegrationsApi`	`deleteS3Config`	`DELETE /v1/integrations/s3`
`IntegrationsApi`	`testS3Connection`	`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