Name: PDF Generator API: Invoices, HTML to PDF, PDF Tools
Brand: pdfgenerator-api
SKU: api-pdfgenerator-api-document-generation
Availability: InStock
Author: API Market

Michal Liska

# PDF Generator API

## Overview

PDF Generator API creates and processes PDF documents. Generate invoices, contracts and reports from templates with JSON data, convert HTML or a web page URL to PDF, convert PDF pages to images, add text or image watermarks, encrypt, decrypt and optimise PDFs, make them accessible, read and fill PDF form fields, and create EN 16931 e-invoices in UBL, CII, XRechnung and Factur-X. This is the official listing of PDF Generator API, with 18 endpoints.

It is built for SaaS products, ERPs, billing and HR systems and agencies that produce documents at scale. In our tests HTML with an invoice heading came back as a base64 PDF in 1.6 seconds, example.org was printed to PDF in 3.5 seconds, the IRS W-9 form was converted to a PNG, watermarked, optimised, encrypted and filled, its form fields were listed, and a request without HTML content returned a clear `422`.

## Features

*   **18 endpoints**: templates, conversion, PDF services, forms and e-invoices.
*   **Template documents**: fill a template with JSON data and get a PDF or HTML.
*   **Conversion**: HTML to PDF, URL to PDF with wait conditions, and PDF to image.
*   **PDF services**: watermark, encrypt, decrypt, optimise, make accessible, read and fill form fields.
*   **E-invoices**: EN 16931 UBL and CII, XRechnung and Factur-X.
*   **Output**: base64, a file, or a hosted URL for 30 days.

## Use Cases

*   **Billing systems**: generate invoices and e-invoices automatically.
*   **HR and legal tools**: fill contracts and forms from data.
*   **Reporting**: turn HTML reports and dashboards into PDFs.
*   **Document workflows**: watermark, secure and compress PDFs before sending.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/pdfgenerator-api/document-generation
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Convert HTML to PDF

Returns a PDF made from your HTML.

**Method:** `POST`

**Endpoint:** `/conversion/html2pdf`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `content` | body | HTML content | string | Yes | - | - |
| `paper_size` | body | `a0` to `a4`, `legal`, `tabloid` or `letter` | string | No | `a4` | - |
| `orientation` | body | `portrait` or `landscape` | string | No | `portrait` | - |
| `output` | body | `base64` or `file` | string | No | `base64` | - |
| `filename` | body | Document name | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/conversion/html2pdf' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"content": "<html><body><h1>Invoice 42</h1><p>Total: 10 EUR</p></body></html>", "paper_size": "a4", "orientation": "portrait", "output": "base64", "filename": "invoice-42"}'
```

**Example Response (201 Created):**

```json
{
  "response": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..."
}
```

`response` is the PDF as base64, shortened above. Without `content` the API returns `422`:

```json
{
  "message": "The content field is required.",
  "errors": {
    "content": [
      "The content field is required."
    ]
  }
}
```

#### 2. Convert a URL to PDF

Prints a public web page to PDF, optionally after waiting for an element or a JavaScript condition.

**Method:** `POST`

**Endpoint:** `/conversion/url2pdf`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | body | Public URL | string | Yes | - | - |
| `paper_size` | body | Page size | string | No | `a4` | - |
| `orientation` | body | `portrait` or `landscape` | string | No | `portrait` | - |
| `output` | body | `base64` or `file` | string | No | `base64` | - |
| `filename` | body | Document name | string | No | - | - |
| `wait_for_css` | body | CSS selector to wait for before printing | string | No | - | - |
| `wait_for_js` | body | JavaScript expression that must be true before printing | string | No | - | - |
| `wait_timeout` | body | Seconds to wait | integer | No | 30 | 60 |
| `on_wait_timeout` | body | `error` (422) or `print` | string | No | `error` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/conversion/url2pdf' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.org", "paper_size": "a4", "output": "base64", "filename": "example"}'
```

**Example Response (201 Created):**

```json
{
  "response": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..."
}
```

#### 3. Convert PDF to images

Returns the pages of a PDF as PNG or JPEG images.

**Method:** `POST`

**Endpoint:** `/conversion/pdf2image`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file_url` | body | Public https URL of the PDF | string | Yes, or `file_base64` | - | - |
| `file_base64` | body | The PDF as base64 | string | No | - | - |
| `format` | body | `png`, `jpeg` or `jpg` | string | No | `png` | - |
| `quality` | body | Image quality | integer | No | 85 | 100 |
| `resolution` | body | DPI | integer | No | 150 | 600 |
| `pages` | body | Page or range, for example `1` or `1-4` | string | No | `all` | - |
| `output` | body | `base64` or `file` | string | No | `base64` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/conversion/pdf2image' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"file_url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "format": "png", "resolution": 72, "pages": "1", "output": "base64"}'
```

**Example Response (201 Created):**

```json
{
  "response": [
    "iVBORw0KGgoAAAANSUhEUgAAAmQAAAMYCAIAAADq5GzlAACAAElEQVR4nO..."
  ]
}
```

`response` holds one base64 image per page.

#### 4. Add a watermark

Adds a text or image watermark to a PDF.

**Method:** `POST`

**Endpoint:** `/pdfservices/watermark`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file_url` | body | Public URL of the PDF | string | Yes, or `file_base64` | - | - |
| `file_base64` | body | The PDF as base64 | string | No | - | - |
| `watermark` | body | `text` (content, color, size, opacity, position, rotation) or `image` (content_url, position, rotation, scale) | object | Yes | - | - |
| `output` | body | `base64` or `file` | string | No | `base64` | - |
| `name` | body | Document name | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/pdfservices/watermark' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"file_url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "watermark": {"text": {"content": "DRAFT", "color": "#ff0000", "size": 48, "opacity": 0.5, "position": "center", "rotation": 45}}, "output": "base64", "name": "wm"}'
```

**Example Response (201 Created):**

```json
{
  "response": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..."
}
```

`/pdfservices/encrypt`, `/pdfservices/decrypt`, `/pdfservices/optimize` and `/pdfservices/make-accessible` take the same `file_url` or `file_base64`, `output` and `name` fields and return the processed PDF the same way. Encrypt also takes `owner_password` and `user_password`.

#### 5. Read PDF form fields

Returns the fillable fields of a PDF form with their names, types and current values.

**Method:** `POST`

**Endpoint:** `/pdfservices/form/fields`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file_url` | body | Public URL of the PDF form | string | Yes, or `file_base64` | - | - |
| `key_field` | body | Field property to key the result by, for example `name` | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/pdfservices/form/fields' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"file_url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "key_field": "name"}'
```

**Example Response (200 OK):**

```json
{
  "response": {
    "topmostSubform[0].Page1[0].Address_ReadOrder[0].f1_07[0]": {
      "id": "934.933.940.947",
      "type": "textfield",
      "name": "topmostSubform[0].Page1[0].Address_ReadOrder[0].f1_07[0]",
      "locked": false,
      "pages": [
        1
      ],
      "value": "",
      "multiline": false
    }
  }
}
```

The `response` object above is shortened to one field. Fill the fields with `/pdfservices/form/fill` by sending `file_url` and a `data` object of field names and values.

#### 6. Generate a document from a template

Fills a template you created in PDF Generator API with JSON data and returns a PDF or HTML.

**Method:** `POST`

**Endpoint:** `/documents/generate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `template` | body | Object with the template `id`, optional `version_id` and the `data` to merge | object | Yes | - | - |
| `format` | body | `pdf` or `html` | string | No | `pdf` | - |
| `output` | body | `base64`, `url`, `file` or `viewer` | string | No | `base64` | - |
| `name` | body | Document name | string | No | - | - |
| `testing` | body | Add a PREVIEW stamp and do not count the document | boolean | No | false | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/documents/generate' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"template": {"id": "YOUR_TEMPLATE_ID", "data": {"invoice_number": "42", "total": "10.00"}}, "format": "pdf", "output": "url", "name": "Invoice 42"}'
```

The response returns the document in `response`, as base64, a hosted URL or the file itself depending on `output`. `GET /templates/schema` returns the JSON schema of a template definition.

#### 7. Check service status

Returns the status of each PDF Generator API service.

**Method:** `GET`

**Endpoint:** `/status`

**Parameters:**

None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/pdfgenerator-api/document-generation/status' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "api": "ok",
  "generator-api-async": "ok",
  "generator-api-sync": "ok",
  "chart-api": "ok",
  "conversion-api": "ok",
  "pdf-services": "ok",
  "e-invoice": "ok"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 201 | Created | The document was created and is in the response body. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 402 | Payment Required | Your PDF Generator API usage limit was reached. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 422 | Unprocessable Entity | A required field is missing or the input file is not a valid PDF. The `errors` object names the field. |
| 429 | Too Many Requests | You went over 4 requests per second. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 4 requests per second. Free includes 20 calls, Individual 50 calls per month for $12, Low-Usage 250 for $35 and Pro 1,000 for $69. Low-Usage and Pro allow overage at $0.15 and $0.08 per call. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Where do template ids come from?**
    Create templates in the PDF Generator API editor. Each template has an id that you pass in `template.id`.

*   **Which e-invoice formats are supported?**
    EN 16931 invoices in UBL or CII syntax, XRechnung and Factur-X with profiles from minimum to extended. `GET /einvoice/schema` returns the JSON payload schema.

*   **How do I get a link instead of base64?**
    Set `output` to `url` on document generation. The file is hosted for 30 days.

*   **Can a URL to PDF wait for my page to finish loading?**
    Yes. Use `wait_for_css` or `wait_for_js` with `wait_timeout`.

*   **How is a call counted?**
    Each request counts as one call. Failed requests are not counted.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Generate invoices, contracts and reports from templates, convert HTML and URLs to PDF, watermark, encrypt and fill PDF forms, and create e-invoices.

PDF Generator API: Invoices, HTML to PDF, PDF Tools