Response Formats

Binary PDF (default) vs the ?format=json base64 envelope — how content negotiation works and what each response looks like.

POST /v1/invoice and POST /v1/receipt support two success-response encodings. Both carry the exact same PDF bytes — this is a response-encoding choice only, applied after validation, VAT calculation, rendering, and quota checks have already succeeded.

Content negotiation

Either signal switches the response to JSON. If both are present, the explicit format query param always wins.

?format=json query param → JSON envelope. ?format=pdf → binary, even if Accept: application/json is also sent.
Else, Accept: application/json (substring match — application/json;q=0.9 also matches) → JSON envelope.
Else → binary. This is the default; existing integrations that never set these see no change.

Error responses are unaffected by this — the error envelope (see Error Codes) is already JSON and identical in both modes.

Binary mode (default)

Response body is the PDF, byte for byte.

text

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-<number>.pdf"
X-InvoicePDF-Version: 1.0.0
X-Request-Id: <uuid-v7>
X-Quota-Remaining: <n>        # when known

JSON mode (?format=json)

Response body is a JSON object. pdf_base64 is the exact PDF bytes, base64-encoded — never a hosted URL. There is no file storage, no expiry, and no cleanup: the API is stateless and does not retain generated documents.

bash

curl -X POST "https://<marketplace-base-url>/v1/invoice?format=json" \
  -H "Content-Type: application/json" \
  -d @invoice.json

Requests are made through the marketplace, not directly to this origin — the real base URL and authentication header name come from the marketplace listing. See Authentication.

json

{
  "filename": "invoice-2026-0042.pdf",
  "content_type": "application/pdf",
  "encoding": "base64",
  "pdf_base64": "<base64 of the exact PDF bytes>",
  "document_type": "invoice",
  "watermarked": false
}

Field	Meaning
`filename`	Suggested filename, same value as the binary mode's `Content-Disposition`.
`content_type`	Always `"application/pdf"`.
`encoding`	Always `"base64"`.
`pdf_base64`	The PDF file, base64-encoded.
`document_type`	`"invoice"` or `"receipt"`, matching the request's `docType`.
`watermarked`	Whether the free-tier "SPECIMEN — NOT A VALID INVOICE" watermark was applied.

Quota and rate-limit headers (X-Quota-Remaining etc.) are still sent as headers in JSON mode — they are not duplicated inside the JSON body.