---
title: "Convert to PDF"
method: POST
path: "/convert/pdf"
---

# Convert to PDF

`POST /convert/pdf`

## Headers

- `X-Processor-Version` '116' | '142'

## Request body

- object
  - `source` union, required — Original document to convert to PDF. PDFShift will automatically detect if it's an URL and load it, or an HTML document and charge it. You can also send an array of documents to convert if parallel conversions is enabled on your account. In that case, you will also need to provide the webhook parameters as this operation is asynchronous.
    - string
    - string[]
  - `sandbox` boolean — Will generates documents that doesn't count in the credits. The generated document will come with a watermark and you are limited to 10 documents per minutes.
  - `encode` boolean — Will return the generated PDF in Base64 encoded format, instead of raw.
  - `filename` string — Name of the destination file. Only an alphanumerical value with "-" or "_", of at least 7 chars accepted. If given, the response **will not be the PDF**, but a JSON response containing an url parameter to an Amazon S3 bucket, to download the file. The file will be **kept for 2 days**, then automatically deleted. See [Saving the document to Amazon S3](/docs/saving-to-s3) for an example.
  - `s3_destination` string — Path to your S3 bucket, in order to save the converted PDF directly into your AWS S3 account. Use a full path value like `s3://doc-example-bucket/pdfshift/upload/86aa3ede7d05.pdf`. See [Saving to your Amazon S3](/docs/saving/to-s3) for more details. Note that you can also save to [Google Cloud Storage](/docs/saving/to-gs) and reach out to us if you want to store to other services as well
  - `use_print` boolean — Use the print stylesheet instead of the general one.
  - `css` string — Will append this CSS styles to the document before saving it. Can be an URL or a String of CSS rules.
  - `javascript` string — Will execute the given Javascript before saving the document. Can be an URL or a String of JS code.
  - `delay` integer — In milliseconds. Will wait for this duration before capturing the document. Up to 10 seconds max.
  - `timeout` integer — If provided, will kill the page loading at a specified time without stopping with a TimeoutError. Value in seconds.
  - `wait_for` string — Name of a function available globally. When present, PDFShift will wait for this function to return a truthy value (true, 1, a string, etc) or up to 30 seconds, then proceed to the conversion. If the function never returns a truthy value in the allocated time, the conversion will fail with an error.
  - `wait_for_network` boolean — If set to true, will wait that there was no network requests in the last 500ms.
  - `ignore_long_polling` boolean — Will not wait for long-polling request to end before generating the document. This can be helpful when loading a page that have websockets or long running queries that have no impact on the generated document. Requires `wait_for_network` to be set to true, otherwise the conversion never waits for network requests at all.
  - `disable_javascript` boolean — Will not execute the javascript at all in the document.
  - `lazy_load_images` boolean — When set to true, will scroll the page to the bottom to trigger loading the images with lazy loading before saving the document.
  - `raise_for_status` boolean — Won't convert the document if the loaded source (when HTTP) returns a non 2XX response.
  - `webhook` union — An URL where we will send a POST request containing a JSON body similar to when you use the filename parameter. The JSON response will contain a URL key that points to your file, stored on Amazon S3. **Note**: When the conversion fail, we also do a `POST` request to your endpoint, but with an `error` key instead. We recommend you to first check if the body contains the `error` before processing the document, and act accordingly.
    - WebhookForm
      - `url` string, uri, required
      - `method` string
      - `auth` BasicAuthForm
        - `username` string
        - `password` string
      - `headers` object
    - string, uri
  - `auth` BasicAuthForm
    - `username` string
    - `password` string
  - `http_headers` object — List of HTTP headers that you can pass to the request when loading the source URL.
  - `cookies` CookieForm[] — List of cookies you want to send along with the requests when loading the source. They must be provided as an array of objects.
    - `name` string, required
    - `value` string, required
    - `secure` boolean
    - `http_only` boolean
  - `is_hipaa` boolean — When set to True, ensure the conversion's parameters are compliant to HIPAA regulations. This will disable features such as `filename` or `webhook` when the `s3_destination` is managed by PDFShift, to avoid storing any sensitive documents on PDFShift's servers. See [Handling sensitive documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents) for more details.
  - `is_gdpr` boolean — When set to True, ensure the conversion's parameters are compliant to GDPR regulations. This will disable features such as `filename` or `webhook` when the `s3_destination` is managed by PDFShift, to avoid storing any sensitive documents on PDFShift's servers. See [Handling sensitive documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents) for more details.
  - `log_request` boolean — Log the request parameters. Useful for debugging purposes with PDFShift support.
  - `landscape` boolean — Will set the view in landscape mode instead of portrait.
  - `format` string — Format of the document. You can either use the standard values (Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5) or a custom `{width}x{height}` value. For `{width}` and `{height}`, you can indicate the following units: in, cm, mm. . The `{height}` value can be replaced by `auto` to automatically adjust the height to the content. For instance, pasing the format `1024xauto` will set the page width to 1024px and the height to the content height.
  - `disable_backgrounds` boolean — The final document will not have the background images.
  - `remove_blank` boolean — Will analyze the last page of the document. If no content is present in it, the page will be removed. But note that if there are remaining hidden data, header or footer that have been pushed to that page, the page will be kept.
  - `pages` string — Pages to print. Can be one number (`3`), a range (`1-5`), a list (`4,5,6`) or a combination of both (`1-3,6,7`). If the number is higher than the real number of pages, that number will be ignored.
  - `zoom` number — A value between 0.1 and 2. Allows you to increase the zoom in the document for specific purposes. 1 is the default zoom, lower is smaller, higher is bigger.
  - `margin` union — Empty spaces between the outer and the beginning of the content. See the [Margin](/docs/margin) section for more details.
    - MarginForm
      - `top` string
      - `right` string
      - `bottom` string
      - `left` string
    - string
    - integer
  - `header` CustomHeaderFooter
    - `source` string, required — Element to add in the header part of the document. PDFShift will automatically detect if it's an URL and load it, or an HTML data and charge it. Accepted variables are: {{date}} - Formatted print date {{title}} - Title of the HTML document {{url}} - Page URL {{page}} - Current page {{total}} - Total number of pages
    - `height` string — A spacing between the header or footer and the content. For header, it's the space between the header and the beginning of the document. For the footer, it's the space between the end of the document and the bottom of the page.
    - `start_at` integer — Start to display the header/footer at that given page. **Important**: If you send header AND footer, and set a start_at higher than 1, it must be the same for header and footer. For instance, header.start_at = 1 and footer.start_at = 5 is possible. But header.start_at = 2 and footer.start_at = 3 is NOT possible.
  - `footer` CustomHeaderFooter
    - `source` string, required — Element to add in the header part of the document. PDFShift will automatically detect if it's an URL and load it, or an HTML data and charge it. Accepted variables are: {{date}} - Formatted print date {{title}} - Title of the HTML document {{url}} - Page URL {{page}} - Current page {{total}} - Total number of pages
    - `height` string — A spacing between the header or footer and the content. For header, it's the space between the header and the beginning of the document. For the footer, it's the space between the end of the document and the bottom of the page.
    - `start_at` integer — Start to display the header/footer at that given page. **Important**: If you send header AND footer, and set a start_at higher than 1, it must be the same for header and footer. For instance, header.start_at = 1 and footer.start_at = 5 is possible. But header.start_at = 2 and footer.start_at = 3 is NOT possible.
  - `metadata` object — Allows you to add custom metadata to the generated PDF document. The following metadata are reserved and thus not accepted: 'author_raw', 'creator_raw', 'producer', 'producer_raw', 'subject_raw', 'title_raw'.
  - `protection` ProtectionForm
    - `author` string — Author metadata for the PDF.
    - `user_password` string — Password required to open the PDF.
    - `owner_password` string — Password required to change permissions.
    - `no_print` boolean — Disallow printing of the PDF.
    - `no_copy` boolean — Disallow copying content from the PDF.
    - `no_modify` boolean — Disallow modifying the PDF.
  - `watermark` WatermarkForm
    - `source` string — PDF source. Must be a valid URL or a base64 encoded PDF document.
    - `image` string — Image source for watermark.
    - `text` string — Text to use as watermark.
    - `font_size` integer — Font size for text watermark (5-300).
    - `font_family` 'Helvetica' | 'Times' | 'Courier' — Font family for text watermark.
    - `font_color` string — Font color in hexadecimal (e.g. #000000 or 000000).
    - `font_opacity` integer — Font opacity percentage (0-100).
    - `font_bold` boolean — Bold font for text watermark.
    - `font_italic` boolean — Italic font for text watermark.
    - `offset_x` string — Horizontal offset: 'left', 'right', 'center', or value ending with px/in/cm/mm/pt.
    - `offset_y` string — Vertical offset: 'top', 'bottom', 'middle', or value ending with px/in/cm/mm/pt.
    - `rotate` integer — Rotation angle for watermark (-359 to 359).

## Response `200`

PDF file generated successfully

- object
  - `success` boolean, required
  - `url` string, uri, required
  - `filesize` integer, required
  - `duration` integer, required
  - `response` object, required
  - `executed` string, date-time, required
  - `pdf_pages` integer

## Other responses

- `202` — Conversion request accepted and queued for processing. Returned when the `webhook` parameter is used.
- `400` — Bad request. Data passed to the request were invalid or wrongly formatted.
- `401` — Unauthorized. Invalid auth key, missing, or disabled.
- `403` — Forbidden. No remaining credits left.
- `408` — Request Timeout. The requested page took too long to load.
- `429` — Too Many Requests. You have been rate limited.
- `500` — Internal Server Error.

---

[API](https://skmtc.dev/pdfshift/apis/pdfshift-api-documentation.md) · [All operations](https://skmtc.dev/pdfshift/apis/pdfshift-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pdfshift/pdfshift-api-documentation/revisions/0b8cbae61b89/schema)