Download invoice as PDF

GEThttps://app.speybooks.com/api/v1/invoices/{id}/pdf

Generate and download an invoice as a PDF file.

The PDF is rendered on the server from the invoice's current data: the invoice and its contact, the line items in their display order, and the organisation's own details. Monetary values are rendered at full precision. The result is returned as a binary PDF, not a JSON envelope.

Authentication

Requires authentication. The caller must belong to the organisation that owns the invoice, and access is scoped to that organisation.

Response format

This endpoint returns a binary PDF rather than the usual JSON envelope:

  • Content-Type: application/pdf
  • Content-Disposition: attachment; filename="INV-0042.pdf"
  • Content-Length set to the size of the PDF

The filename is derived from the invoice number, with any character other than a letter, digit, or hyphen replaced by an underscore.

PDF content

The rendered PDF includes:

  • the organisation header (name, address, VAT and company number)
  • the contact details (name, address, VAT number)
  • the invoice metadata (number, issue date, due date, status)
  • the line item table (description, quantity, unit price, VAT rate, VAT amount, line total)
  • the financial summary (subtotal, VAT, total, amount paid)
  • the notes and terms, when present

Side effects

Downloading a PDF does not change the invoice or its status. Each download records an INVOICE_PDF_DOWNLOADED entry in the audit log, with the invoice number, the caller's IP address, and the user agent.

Caching

PDFs are generated fresh on every request; there is no server-side caching, so a download always reflects the invoice's current state.

Error responses:

  • 400 { code: "invalid_id" }: malformed or wrong-prefix ID
  • 404 { code: "not_found" }: invoice does not exist or belongs to another organisation

curl tip: use -OJ to save with the server-provided filename, or -o invoice.pdf to choose your own.

Path parameters

idstringrequired
Invoice ID (e.g., inv_42)

Response

200Returns the invoice as a PDF binary stream. Content-Type is application/pdf with a Content-Disposition attachment header.

Error codes

400Invalid invoice ID format.
404Invoice not found or does not belong to this organisation.