Heyzine API
Application programming interface for developers or NoCode tools to integrate flipbooks in applications or workflows.
Getting started
Heyzine uses API keys to authenticate the conversions. You have to provide an API key on every request. Both the manually and API converted flipbooks will show up on the Heyzine dashboard.
Login or register to view your api key here.
It's possible to convert a PDF with a simple link, API rest calls, or by using a javascript plugin to convert all the PDF links of a page automatically.
PDF to flipbook conversion with link
Create a link with parameters pointing to your pdf file and use it in anchors, iframes, dialogs, or anywhere else.
The link will redirect to the final flipbook url. The conversion process starts with the first access, so it can take some time to load the first time you open it.
URL: https://heyzine.com/api1?pdf={pdfLink}&k={apiKey}
Examples
https://heyzine.com/api1?pdf=http://www.pdf995.com/samples/pdf.pdf&k=d3m0
https://heyzine.com/api1?pdf=http://www.pdf995.com/samples/pdf.pdf&t=Test title&s=Test subtitle&d=1&k=d3m0
See the parameter reference for all the available customizations through the API.
To convert server-side to avoid revealing the original url, you can use the /rest path and get a json response.
PDF to flipbook REST API
Call the REST endpoint client or server-side, to convert the PDF and get a JSON response with the links to the flipbook, thumbnail, and PDF.
The endpoint will send the response right after the conversion ends. You have to make sure the client has a long enough time out for the largest documents.
URL: https://heyzine.com/api1/rest?pdf={pdfLink}&k={apiKey}
Example REST
Request:
https://heyzine.com/api1/rest?pdf=http://www.pdf995.com/samples/pdf.pdf&k=d3m0
Response:
{
"url": "https://heyzine.com/flip-book/1f083f5b3e.html",
"thumbnail": "https://cdnc.heyzine.com/flip-book/cover/1f083f5b3e.jpg",
"pdf": "https://cdnc.heyzine.com/flip-book/pdf/1f083f5b3ee73a562ca27afc0e2cfa29ba9eeedc.pdf"
}
See the parameter reference for all the available customizations through the API.
Asynchronous requests
Call the Async REST endpoint to get the JSON response immediately in case you don't want to wait for the conversion process.
Subsequent calls to the endpoint with the same parameters will return the current state of the conversion. (started, processed, or failed). During the conversion time, flipbook links will show a not-found page.
URL: https://heyzine.com/api1/async?pdf={pdfLink}&k={apiKey}
Example REST Async
Request:
https://heyzine.com/api1/async?pdf=http://www.pdf995.com/samples/pdf.pdf&k=d3m0
Response:
{
"url": "https://heyzine.com/flip-book/1f083f5b3e.html",
"thumbnail": "https://cdnc.heyzine.com/flip-book/cover/1f083f5b3e.jpg",
"pdf": "https://cdnc.heyzine.com/flip-book/pdf/1f083f5b3ee73a562ca27afc0e2cfa29ba9eeedc.pdf",
"state": "processed"
}
See the parameter reference for all the available customizations through the API.
Conversion parameters reference
| Parameter | Required | Description |
|---|---|---|
| required | Url pointing to the pdf to be converted. Must be a direct link to PDF correctly url encoded. | |
| k | required | Api key for the conversion. Get the key for free above |
| tpl | optional | Flipbook ID to use as a template. It copies the logo, page effect, background, controls, and all the styles. It doesn't copy the access list and interactions. |
| t | optional | Title shown in the pdf page |
| s | optional | Subtitle shown in the pdf page |
| d | optional | Allow downloading the original pdf |
| fs | optional | Show the fullscreen button. fs=1 to show it. |
| sh | optional | Show the share button. sh=1 to show it. |
| pn | optional | Show the previous and next buttons. pn=1 to show it. |
| st | optional | Show the title, subtitle and description on the flipbook's background. st=1 to show it. |
| bg | optional | Remove the background image and use a solid hex color. bg=00000 for black bg=ffffff for white background |
| lg | optional | Url pointing to the company logo you want to place in the flipbook |
Find the ID of a flipbook on your account
jQuery PDF to flipbook
jQuery plugin to convert all the PDF links on your site to flipbooks.
Usage steps:
1.-Include jquery and the plugin through a CDN or download and include them in your project:
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script type="text/javascript" src="https://cdnc.heyzine.com/release/jquery.pdfflipbook.4.js"></script>
2.-Call the plugin with the key to convert all the links:
$('a').pdfFlipbook({ key: 'd3m0' });
3.-Optionally, you can use DOM attributes to customize the resulting flipbook and presentation:
| Parameter | Required | Description | Example |
|---|---|---|---|
| flipbook | Optional | When the element has an href, this attribute will be ignored, otherwise defines the url of the pdf file and binds a click event for navigation. | <span flipbook="/link-to-pdf.pdf">This is a flipbook</span> |
| title | Optional | Title for the page | <a flipbook="/link-to-pdf.pdf" title="title">This is a flipbook</a> |
| subtitle | Optional | Subtitle for the page | <a flipbook="/link-to-pdf.pdf" subtitle="subtitle">This is a flipbook</a> |
| showdownload | Optional | Show the download button on the flipbook page | <a flipbook="/link-to-pdf.pdf" showdownload>This is a flipbook</a> |
| showmodal | Optional | Opens the flipbook in a simple modal over the page | <a flipbook="/link-to-pdf.pdf" showmodal>This is a flipbook</a> |
See the jquery demo here: Demo
oEmbed API
oEmbed is an API that allows third-party websites and apps to fetch an Html embed code to display Heyzine flipbooks.
Discovering oEmbed URIs
Most flipbooks support oEmbed. Your application can discover the corresponding oEmbed URI by searching the flipbook for a element with the type "application/json+oembed".
For example, the flipbook sample here, includes the following link tag:
<link rel="alternate" type="application/json+oembed" href="https://heyzine.com/api1/oembed?url=https%3A%2F%2Fheyzine.com%2Fflip-book%2Fdce36e099f.html&format=json" title="PDF to Flipbook | Heyzine" />
Using oEmbed data from Heyzine in your app or website
Send a GET request to /api1/oembed, with the url parameter set to a flipbook link to get his oEmbed data.
Heyzine supports the standard oEmbed 1.0 parameters (url, format, maxwidth, and maxheight).
Request:
https://heyzine.com/api1/oembed?url=https%3A%2F%2Fheyzine.com%2Fflip-book%2Fdce36e099f.html&format=json
Response:
{
"type": "rich",
"version": "1.0",
"title": "Venice guide",
"provider_name": "Heyzine",
"provider_url": "https:\/\/heyzine.com",
"html": "<iframe allowfullscreen=\"allowfullscreen\" scrolling=\"no\" class=\"fp-iframe\" style=\"width: 100%; height: 600px;\" src=\"https:\/\/heyzine.com\/flip-book\/dce36e099f.html\"><\/iframe>",
"width": 1920,
"height": 2717,
"thumbnail_url": "https:\/\/heyzine.com\/files\/uploaded\/v2\/dce36e099f71f95449f722bfc227cb4bdd1b30f0.pdf-thumb.jpg",
"thumbnail_width": 400,
"thumbnail_height": 566
}
Webhooks
Heyzine supports webhooks to notify events to an external endpoint URL with a predefined frequency.
Access your account webhooks section to define the endpoints and frequency.
Leads Webhook
The webhook will be called each time new leads are collected on any lead generation form in the account.
Request body reference:
data: {
"id_webhook": Identifier of the event,
"date": Date an time (UTC) of the event request,
"leads": [
0: {
date: Date and time (UTC) when the lead was collected,
first_value: Answer to the first field on the form,
second_value: Answer to the second field on the form,
flipbook: {
id: Identifier of the flipbook containing the form,
title: Title set on the publish settings of the flipbook
},
answer: [
0: {
label: Question on the form,
value: Lead answer,
},...
]
},...
]
}
API limits
With the free plan, you have up to 5 free flipbooks, after that the oldest will be removed.
With subscription you have unlimited conversions.
