SnazzyPDF API Documentation

Last Updated: Sep 6, 2024

Welcome to the SnazzyPDF API documentation! This guide is mostly designed for software developers familiar with web technologies like HTTP, and it will walk you through the process of converting JSON data into PDF documents using our API.

Converting Data Using the Web User Interface

In addition to the API, you can also convert JSON data into PDF documents using our easy-to-use web user interface. Currently, the web version supports all features in the API except custom style rules. To convert JSON data into a PDF document, please follow these instructions:

Log in to your account.
Click the "Convert" button located in the top right corner of your browser window.
On the left side of the new window, labeled "JSON," either drag and drop your JSON file or copy and paste your data into the designated area.
If you'd like to customize your PDF document, click "Configure" and choose from the available options.
Once your JSON data is valid, the "Convert" button will become clickable. If it remains disabled and displays "Invalid JSON," check your data for correct formatting and try again.
After the PDF document is generated, a preview will appear in the area labeled "PDF" on the right side of the window. You can click "Maximize" for a larger view or "Download" to save the file. Please ensure you download any important files, as your data will be lost if you leave the page or close your browser.
To convert more data, click the "Convert another" button. Please note that any unsaved data will be lost when you select this option.

API Overview

The SnazzyPDF API allows you to convert JSON data into customizable PDF documents. You can configure various aspects of the PDF output, including locale settings, document styling, and page formatting. The API processes the JSON object you provide in the request body and returns a binary PDF file stream as the response.

JSON Structure and Constraints

Root Level: The JSON structure must have an object at the root level.
Depth Limitation: The JSON object can be nested up to a maximum of 10 levels. Each nested object or array counts as one level of depth.
Size Limitation: The size of your JSON is limited based on your subscription plan. Please visit your profile page for specific details.

Rate Limiting

To ensure stability of the service and to prevent abuse, the API is rate-limited. The current limit is two requests per second per API key. If you exceed this rate, the API will return an HTTP status code 429 (Too Many Requests).

Versioning

The API is versioned to ensure backward compatibility. Each endpoint is tagged with a version number, allowing you to continue using older versions even after updates are released. Critical bug fixes may alter the behavior of previous versions, we try our best to minimize such changes.

Currently, the following versions are available:

Version	Updated	Endpoint URL
v1	Sep 6, 2024	https://api.snazzypdf.com/v1

Headers

To use the SnazzyPDF API, you must include your API key in your request header. You must also set the content-type header:

Authorization: ApiKey <your-api-key-here>
Content-Type: application/json

Example Usage

To help you get started with the SnazzyPDF API, here is an example showing how to convert a JSON object into a PDF document using cURL and SnazzyPDF:

curl -X POST https://api.snazzypdf.com/v1 \
    -H 'Authorization: ApiKey <your-api-key-here>' \
    -H 'Content-Type: application/json' \
    -d '{"hello": "world"}' \
    -f -o helloworld.pdf

Document Configuration

The "$config" property is an optional part of the input JSON that allows you to customize the PDF output. To use custom configuration, set the property "$config" at the root level of your JSON object. The following properties are available:

Property	Type	Default	Required	Validation	Description
title	string	`"Unnamed Document"`	No	1-50 characters	Title of the document. This will appear in document body, default header and footer, PDF metadata and can be referred to in header and footer using the `"{{title}}"` placeholder.
id	string	Random identifier, for example `"5QR9-0SDO-1FNF-ENSO"`	No	1-50 characters	Identifier of the document. This will appear in default header and footer and can be referred to in header and footer using the `"{{id}}"` placeholder.
locale	string	`"en"`	No	Must be a valid Unicode locale identifier, for example `"en"`,`"en-US"` or `"de"`.	Locale of the document, used for date, time and number formatting.
timezone	string	`"UTC"`	No	Must be a valid time zone identifier, for example `"UTC"`,`"US/Eastern"` or `"Europe/Berlin"`. See list of time zones.	Time zone of the document, used for date and time formatting.
format	string	`"letter"`	No	Must be `"letter"`, `"legal"` or `"a4"`.	Paper size of the PDF document.
header	object		No	Can contain optional properties `"left"`, `"center"` and `"right"`. Each value should be an array of up to three strings, maximum of 50 characters each. For example:`{ "left": [ "Left side first row", "Left side second row" ], "right": [ "Right side first row" ] }`	Custom header that will be added to each page in the PDF document. You can use the following placeholders: `"{{date}}"` for current date `"{{title}}"` for document title `"{{id}}"` for document ID `"{{page}}"` for current page `"{{pages}}"` for total number of pages in the document Custom headers and footers are only available in Business or Enterprise plans.
footer	object		No	Same as in header.	Custom footer that will be added to each page in the PDF document. You can use the same placeholders as in header.
styles	array		No	Array of objects, each object must have `"path"` and `"component"` properties. For example: `[ { "path": "$.foo", "component": "inline-list" }, { "path": "$.bar[*]", "component": "vertical-list" } ]`	List of custom style rules. The property `"path"` is used to find the matching entry in the JSON data. The path must start with `"$"`, which represents the root of the JSON object, followed by properties separated by dots. For example: `"$.property.subproperty"`. Brackets can be used to access specific array elements, for example: `"$.property[2].subproperty"`. The `""` wildcard can be used to represent any property or array element at that level. For example: `"$.property[].subproperty"` or `"$..subproperty"`. The double wildcard `""` can be used to represent any sequence of characters. For example, `"$*.subproperty"` would match each property named `"subproperty"` in any depth in the tree. The property `"component"` is used to select how that data is displayed. Allowed values are: `"inline-list"` `"vertical-list"` `"vertical-table"` `"horizontal-table"` `"top-level-table"` `"text"` `"number"` `"boolean"` `"null"` `"date-text"` `"stringify"` See section "Components" for more information.

Components

By default, SnazzyPDF automatically selects the most appropriate component to display your data based on its type, depth, and structure. However, if you prefer a specific presentation, you can define custom style rules within the "$config.styles" property to override the default settings.

Each component has specific requirements for data type and structure. If your custom style rule conflicts with these requirements, SnazzyPDF will revert to the default component type. The following components are available:

Component	Allowed data type(s)	Validation	Description
`"inline-list"`	array		Inline list. Elements are separated by a comma.
`"vertical-list"`	array		Vertical list. Elements are separated by a comma.
`"vertical-table"`	object		Vertical table. Property names are visible at the left hand side and values at the right hand side.
`"horizontal-table"`	array	Array values must be objects with equal properties. For example: `[ {"a": 1, "b": 2}, {"a": 5, "b": 54} ]`	Horizontal table. Property names are visible at the header on top and values are laid horizontally under the header, one row per object.
`"top-level-table"`	object		Properties are shown as headings, values are visible under the headings.
`"text"`	string		Shows unformatted text data.
`"number"`	number		Numeric data, formatted based on the locale.
`"boolean"`	boolean		Boolean values, displayed as YES or NO.
`"null"`	null		Null values, displayed as N/A.
`"date-text"`	string	Valid ISO date string	Date or date time, formatted based on the locale.
`"stringify"`	any		Stringified raw JSON data.

Errors

Upon a successful request, the API responds with an HTTP status 200. If the request fails, the API returns an error. The response body will be JSON data with the following properties:

Error: The error code described below.
ReqId: Unique identifier tied to the request, include this value to any requests for support.
Details: Optional, additional information about the error.

Below is a list of possible errors:

HTTP status	Error	Description
400	INVALID_CONTENT_TYPE	The `Content-Type` header had an incorrect value. The correct value is always `application/json`.
400	INVALID_JSON	The JSON data in the request body was incorrect. Either it's not a valid JSON, or it does not follow the constraints and limitations described in this document. See the details field of the response for more information.
500	INTERNAL_SERVER_ERROR	An unexpected error happened. Contact support for help.
403	FORBIDDEN	Operation is not allowed. Your API key is incorrect or expired.
401	UNAUTHORIZED	API key is missing from the request.
429	QUOTA_EXCEEDED	You have run out of quota. Please upgrade your plan or wait until the next period starts.
503	TEMPORARILY_UNAVAILABLE	The service is under maintenance or heavy load and cannot process your request at the moment. Please try again later.
400	TOO_MANY_PDF_PAGES	The generated PDF documents has too many pages. Please split your data into smaller objects or upgrade your plan.
400	PAYLOAD_TOO_LARGE	Your JSON data is too large. Please split your data into smaller objects or upgrade your plan.