Go SDK & REST Examples — TemplateFox

Two ways to use the TemplateFox API from Go:

SDK (github.com/TemplateFoxPDF/gosdk) — typed client auto-generated from our OpenAPI spec. Recommended.
REST — the stdlib net/http package. Useful for minimal dependencies or endpoints not yet in the SDK.

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

Installation

go get github.com/TemplateFoxPDF/gosdk

The REST variant only needs the stdlib (net/http, encoding/json).

Configuration

Set your API key once and reuse the client.

import (
  "context"
  "os"

  templatefox "github.com/TemplateFoxPDF/gosdk"
)

config := templatefox.NewConfiguration()
config.AddDefaultHeader("x-api-key", os.Getenv("TEMPLATEFOX_API_KEY"))

client := templatefox.NewAPIClient(config)
ctx := context.Background()

import (
  "net/http"
  "os"
)

const baseURL = "https://api.templatefox.com"

func setHeaders(req *http.Request) {
  req.Header.Set("x-api-key", os.Getenv("TEMPLATEFOX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")
}

Generate a PDF

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

request := templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data: map[string]interface{}{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
      "amount":         "$1,234.56",
  },
}

response, _, err := client.PDFApi.CreatePdf(ctx, request)
if err != nil {
  log.Fatal(err)
}

fmt.Println(*response.Url)              // signed URL valid 24h
fmt.Println(*response.CreditsRemaining) // credits left on the team

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data": map[string]string{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
      "amount":         "$1,234.56",
  },
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
  URL              string `json:"url"`
  CreditsRemaining int    `json:"credits_remaining"`
}
json.NewDecoder(resp.Body).Decode(&result)

See Create PDF for every supported parameter.

Save the PDF to a file

response, _, err := client.PDFApi.CreatePdf(ctx, templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"customer_name": "Jane Doe"},
})
if err != nil {
  log.Fatal(err)
}

pdfResp, _ := http.Get(*response.Url)
defer pdfResp.Body.Close()

file, _ := os.Create("invoice.pdf")
defer file.Close()
io.Copy(file, pdfResp.Body)

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data":        map[string]string{"customer_name": "Jane Doe"},
  "export_type": "binary", // PDF bytes returned directly
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

file, _ := os.Create("invoice.pdf")
defer file.Close()
io.Copy(file, resp.Body)

Upload straight to your S3 bucket

Configure your S3 integration once in the dashboard, then pass StoreS3: true on any call.

storeS3 := true
filepath := "invoices/2026/04/"   // key prefix (optional)
filename := "invoice-001"          // no extension, .pdf appended

request := templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"invoice_number": "INV-001"},
  Filename:   &filename,
  StoreS3:    &storeS3,
  S3Filepath: &filepath,
  // S3Bucket:  &bucket,    // override bucket from integration
}

response, _, _ := client.PDFApi.CreatePdf(ctx, request)
fmt.Println(*response.S3Bucket, *response.S3Key)

payload, _ := json.Marshal(map[string]any{
  "template_id":  "YOUR_TEMPLATE_ID",
  "data":         map[string]string{"invoice_number": "INV-001"},
  "filename":     "invoice-001",           // no extension
  "store_s3":     true,                     // upload to your bucket
  "s3_filepath":  "invoices/2026/04/",     // key prefix (optional)
  // "s3_bucket": "custom-bucket",         // override bucket
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

PDF/A compliance

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

variant := "pdf/a-2b"   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"

response, _, _ := client.PDFApi.CreatePdf(ctx, templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"customer_name": "John Doe"},
  PdfVariant: &variant,
})

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data":        map[string]string{"customer_name": "John Doe"},
  "pdf_variant": "pdf/a-2b",   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

Async generation with webhooks

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

payload, _ := json.Marshal(map[string]any{
  "template_id":    "YOUR_TEMPLATE_ID",
  "data":           map[string]string{"invoice_number": "INV-001"},
  "webhook_url":    "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",   // HMAC-SHA256 signing
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create-async", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct{ JobId string `json:"job_id"` }
json.NewDecoder(resp.Body).Decode(&result)
// 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 net/http directly until then.

Error handling

response, httpResp, err := client.PDFApi.CreatePdf(ctx, request)
if err != nil {
  if apiErr, ok := err.(templatefox.GenericOpenAPIError); ok {
      fmt.Printf("status=%d body=%s\n", httpResp.StatusCode, apiErr.Body())
  }
  log.Fatal(err)
}

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

if resp.StatusCode >= 400 {
  body, _ := io.ReadAll(resp.Body)
  log.Fatalf("status=%d body=%s", resp.StatusCode, string(body))
}

See Error codes for the full list.

Available SDK methods

Service	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