---
title: "Create a PDF"
method: POST
path: "/v1/pdf"
tags: ["PDFs"]
---

# Create a PDF

`POST /v1/pdf`

## Request

- Base URL: `https://api.castpdf.com`
- URL: `https://api.castpdf.com/v1/pdf`
- Auth: HTTP bearer

Renders a template (template_id) or raw html. response: binary (default, the PDF) or url (JSON with a signed link). With async: true the answer is 202 and the result arrives as pdf.created or pdf.failed. deliver.email emails the PDF. test: true makes a watermarked test document (not counted) even with a live key. e_invoice issues a structured invoice as Factur-X / ZUGFeRD (a PDF/A-3b with the XML embedded) or XRechnung (the XML itself, application/xml); see the EInvoice schema. merge_data is for no-code forms (GET /v1/templates/{id}/fields, tree): its empty values (null, empty strings, empty objects and arrays) are dropped and the rest is deep-merged over data. The JSON answer (response: url) carries every Document field, plus filename, metadata, warnings and blocked_resources.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `template_id` string
  - `template_version` integer
  - `html` string
  - `css` string
  - `data` object
  - `merge_data` object
  - `mode` 'fast' | 'print'
  - `format` union
    - 'A4' | 'A5' | 'Letter' | 'Legal'
    - object
      - `width` string, required
      - `height` string, required
  - `orientation` 'portrait' | 'landscape'
  - `margins` string
  - `filename` string
  - `response` 'binary' | 'url'
  - `metadata` object
  - `async` boolean
  - `deliver` object
    - `email` object
      - `to` string
      - `subject` string
      - `message` string
      - `reply_to` string
  - `test` boolean
  - `e_invoice` EInvoice: Issue a structured invoice as an EU e-invoice. data may be left out (the template data is derived from the invoice), and so may template_id and html (the built-in invoice template is used). Counts as one document.
    - `standard` 'factur-x' | 'zugferd' | 'xrechnung-cii' | 'xrechnung-ubl', required: factur-x and zugferd: a PDF/A-3b with the CII XML embedded (factur-x.xml). xrechnung-cii and xrechnung-ubl: the XRechnung 3.0 XML itself (application/xml), nothing rendered.
    - `profile` 'minimum' | 'basic-wl' | 'basic' | 'en16931' | 'extended' | 'xrechnung': factur-x: minimum, basic-wl, basic, en16931 (default) or extended. zugferd: the same, or xrechnung (the XRechnung CII embedded as xrechnung.xml). xrechnung-*: xrechnung.
    - `invoice` object, required
      - `number` string, required: BT-1 invoice number.
      - `type_code` string: BT-3, UNTDID 1001. Default 380 (invoice); 381 credit note, 384 corrected invoice, 389 self-billed. XRechnung allows 326, 380, 381, 384, 389, 875, 876, 877.
      - `issue_date` string, date, required: BT-2. YYYY-MM-DD.
      - `currency` string, required: BT-5, ISO 4217, for example EUR.
      - `buyer_reference` string: BT-10. For XRechnung this is the Leitweg-ID and it is required.
      - `purchase_order_reference` string: BT-13.
      - `sales_order_reference` string: BT-14.
      - `contract_reference` string: BT-12.
      - `project_reference` string: BT-11.
      - `preceding_invoice` object: BG-3: the invoice a credit note or correction refers to.
        - `number` string, required: BT-25.
        - `issue_date` string, date: BT-26. YYYY-MM-DD.
      - `delivery_date` string, date: BT-72 actual delivery date. YYYY-MM-DD.
      - `billing_period` object
        - `start` string, date, required: BT-73. YYYY-MM-DD.
        - `end` string, date, required: BT-74. YYYY-MM-DD.
      - `notes` string[]: BT-22.
      - `seller` object, required
        - `name` string, required: BT-27 / BT-44 legal name.
        - `trading_name` string: BT-28 / BT-45.
        - `id` string: BT-29 / BT-46 party identifier.
        - `id_scheme` string: ISO 6523 scheme of id, for example 0088 (GLN).
        - `legal_registration_id` string: BT-30 / BT-47 company register number.
        - `legal_registration_scheme` string: ISO 6523 scheme of legal_registration_id.
        - `vat_id` string: BT-31 / BT-48 VAT identification number with country prefix, for example DE123456789.
        - `tax_number` string: BT-32 (seller): national tax number (Steuernummer).
        - `legal_info` string: BT-33 (seller): additional legal information.
        - `electronic_address` object
          - `value` string, required: BT-34 / BT-49.
          - `scheme` string: CEF EAS code: EM email (default), 0204 Leitweg-ID, 9930 German VAT number, 0088 GLN.
        - `address` object, required
          - `line1` string: BT-35 / BT-50 street and number.
          - `line2` string: BT-36 / BT-51.
          - `line3` string: BT-162 / BT-163.
          - `city` string: BT-37 / BT-52.
          - `postal_code` string: BT-38 / BT-53.
          - `subdivision` string: BT-39 / BT-54 region or state.
          - `country_code` string, required: BT-40 / BT-55, ISO 3166-1 alpha-2.
        - `contact` object
          - `name` string: BT-41 / BT-56.
          - `phone` string: BT-42 / BT-57.
          - `email` string: BT-43 / BT-58.
      - `buyer` object, required
        - `name` string, required: BT-27 / BT-44 legal name.
        - `trading_name` string: BT-28 / BT-45.
        - `id` string: BT-29 / BT-46 party identifier.
        - `id_scheme` string: ISO 6523 scheme of id, for example 0088 (GLN).
        - `legal_registration_id` string: BT-30 / BT-47 company register number.
        - `legal_registration_scheme` string: ISO 6523 scheme of legal_registration_id.
        - `vat_id` string: BT-31 / BT-48 VAT identification number with country prefix, for example DE123456789.
        - `tax_number` string: BT-32 (seller): national tax number (Steuernummer).
        - `legal_info` string: BT-33 (seller): additional legal information.
        - `electronic_address` object
          - `value` string, required: BT-34 / BT-49.
          - `scheme` string: CEF EAS code: EM email (default), 0204 Leitweg-ID, 9930 German VAT number, 0088 GLN.
        - `address` object, required
          - `line1` string: BT-35 / BT-50 street and number.
          - `line2` string: BT-36 / BT-51.
          - `line3` string: BT-162 / BT-163.
          - `city` string: BT-37 / BT-52.
          - `postal_code` string: BT-38 / BT-53.
          - `subdivision` string: BT-39 / BT-54 region or state.
          - `country_code` string, required: BT-40 / BT-55, ISO 3166-1 alpha-2.
        - `contact` object
          - `name` string: BT-41 / BT-56.
          - `phone` string: BT-42 / BT-57.
          - `email` string: BT-43 / BT-58.
      - `delivery` object: BG-13 deliver-to.
        - `name` string: BT-70.
        - `address` object
          - `line1` string: BT-35 / BT-50 street and number.
          - `line2` string: BT-36 / BT-51.
          - `line3` string: BT-162 / BT-163.
          - `city` string: BT-37 / BT-52.
          - `postal_code` string: BT-38 / BT-53.
          - `subdivision` string: BT-39 / BT-54 region or state.
          - `country_code` string, required: BT-40 / BT-55, ISO 3166-1 alpha-2.
      - `payment` object
        - `means_code` string: BT-81, UNTDID 4461. Default 58 (SEPA credit transfer) with an iban, else 1.
        - `means_text` string: BT-82.
        - `iban` string: BT-84; the check digits are verified.
        - `account_name` string: BT-85.
        - `bic` string: BT-86.
        - `reference` string: BT-83 remittance information. Default: the invoice number.
        - `terms` string: BT-20 payment terms.
        - `due_date` string, date: BT-9. Either due_date or terms is required when an amount is due. YYYY-MM-DD.
        - `mandate_reference` string: BT-89 SEPA direct debit mandate.
        - `creditor_id` string: BT-90 SEPA creditor identifier.
        - `debited_iban` string: BT-91 debited account.
      - `lines` object[], required
        - `id` string: BT-126; default the position (1, 2, …).
        - `name` string, required: BT-153 item name.
        - `description` string: BT-154 item description.
        - `note` string: BT-127.
        - `seller_item_id` string: BT-155.
        - `buyer_item_id` string: BT-156.
        - `standard_item_id` string: BT-157, with standard_item_scheme (0160 = GTIN).
        - `standard_item_scheme` string: ISO 6523 scheme of standard_item_id.
        - `quantity` union, required: BT-129. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `unit_code` string: BT-130, UN/ECE Rec 20: C62 piece (default), HUR hour, DAY day, KGM kilogram, MTR metre, LS lump sum.
        - `unit_price` union, required: BT-146 net price per unit (after any price discount); not negative. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `price_base_quantity` union: BT-149: the price is for this many units. Default 1. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `order_line_reference` string: BT-132.
        - `period` object: BG-26 line period.
          - `start` string, date, required: Start. YYYY-MM-DD.
          - `end` string, date, required: End. YYYY-MM-DD.
        - `allowances` object[]
          - `amount` union: BT-136 / BT-141, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as "19.99".
            - number
            - string
          - `percent` union: Percent of the line amount (quantity x net price). A JSON number or a decimal string such as "19.99".
            - number
            - string
          - `reason` string: BT-139 / BT-144. A reason or a reason_code is required.
          - `reason_code` string: UNTDID 5189 (allowances, 95 = discount) or UNTDID 7161 (charges).
        - `charges` object[]
          - `amount` union: BT-136 / BT-141, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as "19.99".
            - number
            - string
          - `percent` union: Percent of the line amount (quantity x net price). A JSON number or a decimal string such as "19.99".
            - number
            - string
          - `reason` string: BT-139 / BT-144. A reason or a reason_code is required.
          - `reason_code` string: UNTDID 5189 (allowances, 95 = discount) or UNTDID 7161 (charges).
        - `vat` object, required: The VAT of a line or of a document allowance or charge.
          - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M': UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.
          - `rate` union: Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as "19.99".
            - number
            - string
      - `allowances` object[]: BG-20 document level allowances.
        - `amount` union: BT-92 / BT-99, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `percent` union: Percent of base_amount. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `base_amount` union: Default: the sum of the line net amounts. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `reason` string: BT-97 / BT-104. A reason or a reason_code is required.
        - `reason_code` string: UNTDID 5189 (allowances) or UNTDID 7161 (charges).
        - `vat` object: Required when the lines use more than one VAT category or rate; otherwise the lines' VAT.
          - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M': UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.
          - `rate` union: Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as "19.99".
            - number
            - string
      - `charges` object[]: BG-21 document level charges.
        - `amount` union: BT-92 / BT-99, at most 2 decimals. Give amount or percent. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `percent` union: Percent of base_amount. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `base_amount` union: Default: the sum of the line net amounts. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `reason` string: BT-97 / BT-104. A reason or a reason_code is required.
        - `reason_code` string: UNTDID 5189 (allowances) or UNTDID 7161 (charges).
        - `vat` object: Required when the lines use more than one VAT category or rate; otherwise the lines' VAT.
          - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M': UNTDID 5305: S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export, O not subject to VAT, L Canary Islands, M Ceuta and Melilla. Default S.
          - `rate` union: Percent (19 means 19 %). Required for S, L and M; 0 for Z, E, AE, K and G; left out for O. A JSON number or a decimal string such as "19.99".
            - number
            - string
      - `prepaid_amount` union: BT-113. A JSON number or a decimal string such as "19.99".
        - number
        - string
      - `rounding_amount` union: BT-114 (EN 16931, EXTENDED and XRechnung only). A JSON number or a decimal string such as "19.99".
        - number
        - string
      - `tax_exemptions` object: VAT exemption reason per category (BT-120 text, BT-121 VATEX code). Required for E; AE, K, G and O have defaults.
      - `totals` object: Optional: totals you computed. Each one given is compared with the totals computed from the lines (EN 16931: each line rounded to cents, VAT once per category and rate); a difference is a 400 that names the field.
        - `line_total` union: BT-106. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `allowance_total` union: BT-107. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `charge_total` union: BT-108. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `tax_basis_total` union: BT-109. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `tax_total` union: BT-110. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `grand_total` union: BT-112. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `prepaid` union: BT-113. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `rounding` union: BT-114. A JSON number or a decimal string such as "19.99".
          - number
          - string
        - `due_payable` union: BT-115. A JSON number or a decimal string such as "19.99".
          - number
          - string

## Response `200`

The PDF (response: binary) or its JSON (response: url). An XRechnung e_invoice answers with the XML (application/xml). E-invoices carry the header x-e-invoice: <standard>/<profile>.

- object
  - `id` string, uuid
  - `status` 'queued' | 'processing' | 'succeeded' | 'failed' | 'canceled'
  - `pages` integer, nullable
  - `bytes` integer, nullable
  - `mode` 'fast' | 'print' | 'null', nullable
  - `test` boolean
  - `template_id` string, nullable
  - `template_version` integer, nullable
  - `error_code` string, nullable
  - `created_at` string, date-time
  - `expires_at` string, date-time, nullable
  - `url` string, uri, nullable: Signed download link, valid until expires_at.
  - `thumbnail_url` string, uri, nullable: Signed PNG of the first page (480 px wide) while the PDF is stored; made on first request. In GET /v1/pdf/{id} and GET /v1/documents, not in webhook events.
  - `delivery` object, nullable
    - `email` object
      - `status` 'queued' | 'sent' | 'failed' | 'suppressed'
      - `reason` 'over_limit' | 'not_stored' | 'send_failed': Why a failed email was not delivered.
  - `filename` string
  - `metadata` object, nullable
  - `warnings` object[]
  - `blocked_resources` string[]
  - `e_invoice` object: Only for an e_invoice request.
    - `standard` string
    - `profile` string
    - `xml_filename` string

## Other responses

- `202`: Queued (async: true).
- `default`: Error

---

[API](https://skmtc.dev/castpdf/apis/castpdf-api.md) · [All operations](https://skmtc.dev/castpdf/apis/castpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/castpdf/apis/castpdf-api/revisions/4ec737ba2ba6?raw)