# FlippingBook APIs documentation

Welcome to the FlippingBook API's specification.

This page lists the reference documentation for FlippingBook (opens new window) APIs. The first section, General Information, is about the common concepts of our APIs and their structure. The other two sections, Key Management API and FlippingBook Online API, provide product-specific information.

FlippingBook Online is a service that converts PDFs into interactive digital documents.

# FlippingBook Public APIs: General Information

There are several Public APIs available for your applications. They can all be accessed via our single-host API gateway https://api-tc.is.flippingbook.com/. All APIs require proper authentication/authorization to be used. Almost all APIs share the same error reporting convention.

While using APIs, you should keep in mind that there are certain limitations, and there may be changes to the version you have now in line with the Changes Policy.

API requests and responses must be in a UTF-8 encoded JSON format, regardless of the request's Content-Type, Accept-Charset, and Accept HTTP headers. Requests may also be in a 'relaxed' JSON format: you can use single quotes for strings, and you don’t need to quote property names. On the response side, there will always be Content-Type: application/json header, and the JSON format will strictly follow the standard.

# Authentication

# Authentication Scheme

All publicly available APIs require your application to be authenticated and authorized to make API calls. Authentication is done with the HTTP bearer scheme, so all your requests (unless specified explicitly in the request description) should come with an Authorization HTTP header with the proper value:

GET /api/v1/auth/me HTTP/1.1
Host: api-tc.is.flippingbook.com
Authorization: Bearer <your API key>

# API Keys

To receive your first API key, please contact our support team (opens new window). After that, you can create new keys yourself, following the instructions in Key Management API. You’ll also need the value of AccessToken property for it: to get it, log into your account and go to https://logon.flippingbook.com/myaccesstoken.

API keys are linked to your FlippingBook account, and all actions are recorded and audited. You can’t have more than 10 API keys per account.

# Handling Errors

# General Rules

All API calls may return errors for your requests. We have a standardized error format for all responses unless stated explicitly in the API call description. All responses should follow this structure:

{
  "success": true | false,
  "error": undefined | null | { /* single error object */ }
  "errors": undefined | null | [{ /* single error object */ }, ...]
}

The success property shows the general status of your API call: whether is has succeeded or not. In most cases, it is enough to only handle issues with success == true and ignore/throw errors when success == false.

The error and errors properties are mutually exclusive and contain one or several error objects (description follows), although it is possible for errors to contain zero or one error object items.

Every single error object has the following structure:

{
  "wellKnownError": Number | String,
  "errorCode": undefined | String,
  "message": undefined | null | String
}

Here, wellKnownError and errorCode are machine-readable error codes, and message is human-readable and provides more details on the error for your interpretation.

# HTTP Status Mapping

Although the error/success state may be easily read from the response body, the HTTP status can also indicate success. Successful calls end with 200 OK status, and unsuccessful ones will have 4xx or 5xx errors.

# Universal Errors Codes

Most error codes are application/call specific, however, there are some common ones:

# API Usage Limits

To maintain optimum performance and ensure that the service is available to all our customers, API usage is limited in several ways:

• Request Rate limiting
• General API limitations
• Specific API limitations

# Request Rate Limiting

Each API key is allowed to make up to ten consequent requests without any delay. After that, you can continue making one request per second. If you call our API more often than that, you might have to wait for the requests to be completed, but no longer than 1 extra second for each additional request.

# General API Limitations

API keys are associated with your FlippingBook account. For each account, there may be no more than ten keys. Total request size is limited to 1MB. This limit mainly affect uploads and in case you need to upload bigger file consider using download from URL instead.

# Specific API Limitations

Your purchased plan or edition may limit your access to API features or the entities you’re allowed to use.

# API Changes Policy

We are constantly improving our APIs to support new product features. Still, we do our best to maintain backward compatibility with existing integrations. All APIs are versioned (by the HTTP path, /api/v1/...), and and all breaking changes will only be released in a new API version. Non-breaking changes (like adding new calls, extending responses with new properties, adding properties to requests while keeping the default behavior) may be added to the current version.

# Key Management API

This API is used to control your API keys. Call it to issue new keys or review and revoke existing ones.

# The Key Entity

The Key entity represents an API key used to access all other APIs.

# List all API keys for your account

GET /api/v1/auth/key

This method lists all API keys for your account, including the one you are using to call it.

# Parameters in path and query

# Response format

# Create a new API key for your account

POST /api/v1/auth/key

This method creates a new API key for your account. You must be authorized either with the HTTP Bearer authorization scheme with an existing API key or with your session access token from FlippingBook-its single sign-on service.

# Parameters in request body

# Response format

# Revoke an existing API key

DELETE /api/v1/auth/key

This method irreversibly deletes the currently used API key.

# Response format

# FlippingBook Online API

FlippingBook Online is a service for converting PDFs into interactive digital documents. Its API allows you to programmatically create publications and customize their look and behavior.

Publications are represented as Publication entities which are made up of one or more Source entities. A source represents a publication version and usually corresponds to one source PDF file. Each publication may also contain zero to many Tracked/Individual Links entities that represent a special type of links for that publication with independent tracking, statistics, and notifications.

If your plan gives you the option to add a custom domain, and you have at least one domain set up, then all your publications must be assigned to Custom Domain entities.

To monitor specific events and their status, and to make the integration to external systems easier, use Event triggers.

For simpler API exploration, most entities contain HATEOAS (opens new window) links.

# The Publication Entity

Publications are the main entity of FlippingBook Online. They serve as an entry point for end-users (readers) and represent a document available online with defined behavior and looks. Yet, you can't only create a publication: your application also has to supply its content by defining one or more sources.

# List filtered and/or paged publications in the account

GET /api/v1/fbonline/publication

With this method, your application can retrieve a full/filtered list of publications in your account.

# Parameters in path and query

# Response format

# Retrieve information about a publication by its identifier.

GET /api/v1/fbonline/publication/{id}

With this method, your application can retrieve information on one publication known by its identifier.

# Parameters in path and query

# Response format

# Create a new publication possibly attaching a new source file.

POST /api/v1/fbonline/publication

Using this method, your application may create a publication and its initial source file in one request. As an alternative, the source file may be omitted and created later with a corresponding call.

# Parameters in request body

# Response format

# Update the metadata for one publication, possibly attaching a new source file.

POST /api/v1/fbonline/publication/{id}

With this method, your application may update the publication name and description, and possibly update the underlying PDF source file.

# Parameters in path and query

# Parameters in request body

# Response format

# Update the publication's customization (look and behavior)

POST /api/v1/fbonline/publication/{id}/customize

With this method, your application may modify how the publication looks and change its behavior.

# Parameters in path and query

# Parameters in request body

# Response format

# Delete publication

DELETE /api/v1/fbonline/publication/{id}

With this method, your application can mark a publication for deletion.

# Parameters in path and query

# Response format

# The Source Entity

Sources represent the publication's content. Each publication can have more than one source, however, only the last converted source will be displayed to end-users (readers). For now, the only supported format for the source is a single PDF file that is not password-protected and does not contain XFA (forms). There's a limit on PDF file size (500Mb) and the number of pages (2000). Total request size should not exceed 1MB, it mainly affects base64-encoded PDF uploads (in the data field).

# List all sources for the given publication

GET /api/v1/fbonline/publication/{id}/source

This method allows your application to retrieve the history of sources for a given publication. Although sources cannot be modified once created, you might want to check how many versions the publication has, and what PDFs were they based on.

# Parameters in path and query

# Response format

# Retrieve information about a single source

GET /api/v1/fbonline/publication/{id}/source/{sourceId}

With this method, your application may retrieve information about one publication source by its identifier. It may be useful to monitor the source conversion progress.

# Parameters in path and query

# Response format

# Create a new publication source

POST /api/v1/fbonline/publication/{id}/source

With this method, your application may create a new source for a given publication. Source PDF must be either Base64-encoded and passed within the request, or, preferably, made publicly available on the internet for several minutes and passed as a URL.

# Parameters in path and query

# Parameters in request body

# Response format

# The Tracked Link Entity

A tracked link is a special link (URL) for the publication that offers independent statistics and event handling. For example, you may create a link that sends you, the author, an email when the publication under the tracked link is opened for the first time.

Each link has a separate object for handling its events called a trigger. Link-bound triggers are altered with link's API calls POST trigger and DELETE trigger.

# List tracked links

GET /api/v1/fbonline/tracked_links

This method allows your application to retrieve a list of all tracked links created for your account. Although tracked links are bound to individual publications, they can be fetched in the account context for all publications at once.

# Parameters in path and query

# Response format

# Retrieve information about a single tracked link

GET /api/v1/fbonline/tracked_links/{linkId}

# Parameters in path and query

# Response format

# Create a new tracked link

POST /api/v1/fbonline/tracked_links

With this method, your application may create a new tracked link for an existing publication.

# Parameters in request body

# Response format

# Modify or delete a specified tracked link

PUT /api/v1/fbonline/tracked_links/{linkId}

With this method, your application may update or delete a tracked link.

# Parameters in request body

# Response format

# The Custom Domain Entity

A custom domain is a great way to use your own (sub)domain name in your publications' URL. If you have at least one custom domain in your account, all your publications must be assigned to one.

You can't manage domains via API—only retrieve a list of all available custom domains in your account.

# List all available custom domains.

GET /api/v1/fbonline/custom-domains

With this method, your application can list custom domains available to the current user.

# Response format

# Event Triggers

Triggers provide a way for your application to react to different FlippingBook Online generated events. They can be defined on multiple layers to handle events in different scopes:

• Account-wide triggers: notify about events on any account publication or tracked link.
• Publication level triggers: notify about events on one publication and all tracked links bound to it.
• Tracked link-level triggers: notify about events on one tracked link.

Most of the triggers are created implicitly upon tracked link creation/modification, however, you can manage custom triggers with the event trigger API.

# Create a new trigger

POST /api/v1/fbonline/triggers

With this method, your application may create new triggers. In order for the trigger to work properly, you should set events, and an endpoint.

# Parameters in request body

# Response format

# Update a trigger

POST /api/v1/fbonline/triggers/{id}

With this method, your application can modify a trigger - either the events that cause it to fire, or its webhook address.

# Parameters in path and query

# Parameters in request body

# Response format

# Delete a trigger

DELETE /api/v1/fbonline/triggers/{id}

With this method, your application may delete a trigger by its identifier. After a trigger is deleted, it won't fire anymore and won't be accounted towards your account limit.

# Parameters in path and query

# Response format

# Event Names