FlippingBook Public APIs documentation

# 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:

HTTP Status Code Error code Meaning
400 InvalidData The request body cannot be parsed as JSON.
401 NoAuthorizationHeader Your request does not include an Authorization HTTP header.
401 BadAuthorizationType The HTTP Authorization scheme is not Bearer.
403 InvalidApiKey The API key supplied in the Authorization header is invalid.
404 NotFound The endpoint specified in your request (a combination of HTTP method and path) does not exist.
429 RateLimitExceeded Your application has exceeded the rate limit by making too many API calls within a short period of time.
500 InternalError Your request does not meet the required format, or an internal error has occurred.

# 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.

# 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
Name Description
Query accessToken This parameter is required only if you omit the Authorization HTTP header as a fallback authentication method. The value of accessToken is your session access token from FlippingBook-its single sign-on service. To obtain it, visit https://logon.flippingbook.com/myaccesstoken while logged in to your FlippingBook account (opens new window).
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
keys array An array of active keys for your account.

# 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
Name Type Description
accessToken string This parameter is required only if you omit the Authorization HTTP header as a fallback authentication method. The value of accessToken is a session access token from FlippingBook-its single sign-on service. To obtain it, visit https://logon.flippingbook.com/myaccesstoken while logged in to your FlippingBook account (opens new window).
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
key string The new key for accessing your account via API.

# Revoke an existing API key

DELETE /api/v1/auth/key

This method irreversibly deletes the currently used API key.

# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.

# 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.

TIP

By default, the result is paged by 10 publications. To get information on all your publications, you should either increase the count value (max 1000), or fetch the next pages using the offset parameter.

# Parameters in path and query
Name Description
Query count The number of publications to return. Defaults to 10.
Query offset The starting number of publication to return. Defaults to 0.
Query query Publication filter. In order to match, publication name must contain the exact query value.
Query hashid Publication filter. In order to match, publication identifier (the number in the publication URL) must exactly match the hashid value.
Query url Publication filter. In order to match, publication URL must exactly match the url value.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer The total number of publications matching your request (disregarding offset/count).
publications array Matching publications.
publications.id string Publication's unique identifier. It's permanent, none of your actions will change it.
publications.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications, it may be changed with the help of our support team, so you should not rely on this as a valid/unique publication identifier.
publications.name string Publication name.
publications.description string Publication description.
publications.links array A set of HATEOAS links.
publications.links.rel string The kind of relation with the linked resource.
publications.links.type string The HTTP method to use with this link.
publications.links.href string Link URL.
publications.state string Publication status. It may consist of any combination (comma separated) of the following values: Trashed - the publication was moved to trash, but can still be restored; Deleted - the publication was irreversibly deleted; CompletedAllStages - the publication has at least one source that converted successfully; HasContent, Empty, Published - internal statuses, do not rely on them.
publications.seoEnabled boolean Indicates whether SEO optimization is enabled for the publication. If true, that means web search indexing engines will see the text content of your publication, and it will appear in our sitemap.
publications.ownerHashId string Publication owner identifier. Typically not used.
publications.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing the actual publication (when allowed by its security policy).
publications.cover string Publication cover URL.
publications.canonicalLink string Canonical URL of the publication.
publications.totalPages integer The total number of pages in the publication. This will have a valid value once the publication source has completely converted.
publications.lastPdfName string The filename of the latest uploaded PDF source file.
publications.domain string The domain where the publication is located.
publications.folder string ID of the folder containing the publication.
publications.customizationOptions object Publication looks & behavior settings.
publications.customizationOptions.password string Password for password-protected publications.
publications.customizationOptions.hardcoverEnabled boolean Indicates whether a hardcover is enabled for the publication.
publications.customizationOptions.companyLogoEnabled boolean Indicates whether a company logo display is enabled for the publication.
publications.customizationOptions.companyLogoUrl string The URL that opens when people click on the company logo inside the publication.
publications.customizationOptions.rtlEnabled boolean Indicates whether the publication is in RTL mode (this is designed for Hebrew and Arabic publications, where the page flipping direction and controls layout are reversed).
publications.customizationOptions.theme string The selected skin for the publication.

# 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
Name Description
Path id REQUIRED Publication identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
publication object
publication.id string Publication's unique identifier. It's permanent, none of your actions will change it.
publication.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications, it may be changed with the help of our support team, so you should not rely on this as a valid/unique publication identifier.
publication.name string Publication name.
publication.description string Publication description.
publication.links array A set of HATEOAS links.
publication.links.rel string The kind of relation with the linked resource.
publication.links.type string The HTTP method to use with this link.
publication.links.href string Link URL.
publication.state string Publication status. It may consist of any combination (comma separated) of the following values: Trashed - the publication was moved to trash, but can still be restored; Deleted - the publication was irreversibly deleted; CompletedAllStages - the publication has at least one source that converted successfully; HasContent, Empty, Published - internal statuses, do not rely on them.
publication.seoEnabled boolean Indicates whether SEO optimization is enabled for the publication. If true, that means web search indexing engines will see the text content of your publication, and it will appear in our sitemap.
publication.ownerHashId string Publication owner identifier. Typically not used.
publication.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing the actual publication (when allowed by its security policy).
publication.cover string Publication cover URL.
publication.canonicalLink string Canonical URL of the publication.
publication.totalPages integer The total number of pages in the publication. This will have a valid value once the publication source has completely converted.
publication.lastPdfName string The filename of the latest uploaded PDF source file.
publication.domain string The domain where the publication is located.
publication.folder string ID of the folder containing the publication.
publication.customizationOptions object Publication looks & behavior settings.
publication.customizationOptions.password string Password for password-protected publications.
publication.customizationOptions.hardcoverEnabled boolean Indicates whether a hardcover is enabled for the publication.
publication.customizationOptions.companyLogoEnabled boolean Indicates whether a company logo display is enabled for the publication.
publication.customizationOptions.companyLogoUrl string The URL that opens when people click on the company logo inside the publication.
publication.customizationOptions.rtlEnabled boolean Indicates whether the publication is in RTL mode (this is designed for Hebrew and Arabic publications, where the page flipping direction and controls layout are reversed).
publication.customizationOptions.theme string The selected skin for the publication.

# 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.

TIP

When url or data are specified, the Source entity is created implicitly.

WARNING

If url or data contain invalid values (inaccessible URL, not a PDF file, PDF exceeding limitations), the source is marked as erroneous and, if it was the only source, the publication itself gets deleted.

# Parameters in request body
Name Type Description
name string Publication name. When omitted, the current publication name is left unchanged.
description string Publication description. When omitted, the current publication description is left unchanged.
folder string Folder ID for the publication. When omitted, the current publication folder is left unchanged. When set to null, the publication is moved to the Home folder.
domain string Domain for the publication. When omitted, the current publication domain is left unchanged. Do not specify unless your account has custom domains.
filename string The name of your PDF file.
url string The URL of the PDF file that will be used to create the source for the publication. The URL must be publicly accessible for at least for several minutes.
data string Base64-encoded PDF file content that will be used to create the source for the publication.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Unique publication identifier.
hashId string Publication identifier to use in URLs.
url string Canonical publication URL.
links array A set of HATEOAS links.
links.rel string The kind of relation with the linked resource.
links.type string The HTTP method to use with this link.
links.href string Link URL.
lastModified string Publication's last modification date.
createdSource object
createdSource.success boolean Indicates whether your request was successful or not.
createdSource object
createdSource.wellKnownError string Machine-readable error code.
createdSource.message string Human-readable error message.
createdSource.error string Detailed error code.
createdSource object Source creation result. Present only if data or url were specified in the request.
createdSource.id string Created source's identifier.

# 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.

TIP

When url or data are specified, the Source entity is created implicitly.

WARNING

If url or data contain invalid values (inaccessible URL, not a PDF file, PDF exceeding limitations), the source is marked as erroneous and, if it was the only source, the publication itself gets deleted.

# Parameters in path and query
Name Description
Path id REQUIRED Publication identifier.
# Parameters in request body
Name Type Description
name string Publication name. When omitted, the current publication name is left unchanged.
description string Publication description. When omitted, the current publication description is left unchanged.
folder string Folder ID for the publication. When omitted, the current publication folder is left unchanged. When set to null, the publication is moved to the Home folder.
domain string Domain for the publication. When omitted, the current publication domain is left unchanged. Do not specify unless your account has custom domains.
filename string The name of your PDF file.
url string The URL of the PDF file that will be used to create the source for the publication. The URL must be publicly accessible for at least for several minutes.
data string Base64-encoded PDF file content that will be used to create the source for the publication.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Unique publication identifier.
hashId string Publication identifier to use in URLs.
url string Canonical publication URL.
links array A set of HATEOAS links.
links.rel string The kind of relation with the linked resource.
links.type string The HTTP method to use with this link.
links.href string Link URL.
lastModified string Publication's last modification date.
createdSource object
createdSource.success boolean Indicates whether your request was successful or not.
createdSource object
createdSource.wellKnownError string Machine-readable error code.
createdSource.message string Human-readable error message.
createdSource.error string Detailed error code.
createdSource object Source creation result. Present only if data or url were specified in the request.
createdSource.id string Created source's identifier.

# 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.

WARNING

Although you can set any customization data regardless of your account subscription, the features that are not available for your plan will be filtered upon publication view.

# Parameters in path and query
Name Description
Path id REQUIRED Publication identifier.
# Parameters in request body
Name Type Description
hardCover boolean Whether a hard cover should be enabled for the publication.
setPasswordProtection string How the publication's password protection should be handled: keep to keep the existing configuration; disable to remove password protection; manual to set a new password specified in the manualPassword parameter; numeric to generate a random password with digits only; auto to generate a random password.
manualPassword string A new password to set for the publication.
generatePasswordLength string The length of the to-be generated random password.
logoUrl string A new URL for the company logo to open on click.
enableRtl boolean Whether the RTL mode should be enabled for the publication.
theme string A new skin for the publication.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
publication object
publication.id string Publication's unique identifier. It's permanent, none of your actions will change it.
publication.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications, it may be changed with the help of our support team, so you should not rely on this as a valid/unique publication identifier.
publication.name string Publication name.
publication.description string Publication description.
publication.links array A set of HATEOAS links.
publication.links.rel string The kind of relation with the linked resource.
publication.links.type string The HTTP method to use with this link.
publication.links.href string Link URL.
publication.state string Publication status. It may consist of any combination (comma separated) of the following values: Trashed - the publication was moved to trash, but can still be restored; Deleted - the publication was irreversibly deleted; CompletedAllStages - the publication has at least one source that converted successfully; HasContent, Empty, Published - internal statuses, do not rely on them.
publication.seoEnabled boolean Indicates whether SEO optimization is enabled for the publication. If true, that means web search indexing engines will see the text content of your publication, and it will appear in our sitemap.
publication.ownerHashId string Publication owner identifier. Typically not used.
publication.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing the actual publication (when allowed by its security policy).
publication.cover string Publication cover URL.
publication.canonicalLink string Canonical URL of the publication.
publication.totalPages integer The total number of pages in the publication. This will have a valid value once the publication source has completely converted.
publication.lastPdfName string The filename of the latest uploaded PDF source file.
publication.domain string The domain where the publication is located.
publication.folder string ID of the folder containing the publication.
publication.customizationOptions object Publication looks & behavior settings.
publication.customizationOptions.password string Password for password-protected publications.
publication.customizationOptions.hardcoverEnabled boolean Indicates whether a hardcover is enabled for the publication.
publication.customizationOptions.companyLogoEnabled boolean Indicates whether a company logo display is enabled for the publication.
publication.customizationOptions.companyLogoUrl string The URL that opens when people click on the company logo inside the publication.
publication.customizationOptions.rtlEnabled boolean Indicates whether the publication is in RTL mode (this is designed for Hebrew and Arabic publications, where the page flipping direction and controls layout are reversed).
publication.customizationOptions.theme string The selected skin for the publication.

# Delete publication

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

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

TIP

Publications are not deleted immediately, instead, they are put into a 'deleted' state and deleted irreversibly after a period of time.

# Parameters in path and query
Name Description
Path id REQUIRED The publication identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.

# 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).

WARNING

Once created, sources cannot be updated and/or deleted. On creation, they are put into a conversion queue and are activated (visible in the publication) when the conversion is finished.

# 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
Name Description
Path id REQUIRED Publication identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
sources array Publication sources.
sources.id string Source's unique identifier. Although these IDs are unique across the system, they cannot be used without a publication identifier.
sources.publicationId string Parent publication identifier.
sources.links array A set of HATEOAS links.
sources.links.rel string The kind of relation with the linked resource.
sources.links.type string The HTTP method to use with this link.
sources.links.href string Link URL.
sources.state string The processing state of the source file. It can be one of the following values: WaitAutoQueue - source file upload was completed, but it is not queued for conversion yet; Queued - the source file is in the conversion queue; Completed - the source file has been partially converted, publication preview is available; CompletedAllStages - the source file has been completely converted and was activated in the publication; CompletedWithErrors - there was a permanent error during conversion, re-uploading the same file will not fix it; WaitManualQueue - a special status, never set automatically, meaning the source file upload was completed, but it will not be put in the conversion queue.
sources.stage string The current conversion state (if the source is still converting). At the moment, there are two stages: Preview and L1. After Preview is completed, the source will be activated for the publication only if it does not have any previous successful sources. Publication in the preview mode is customizable, the first few pages can be viewed, and other pages will load as the conversion completes. Preview publications are not optimized for end users, and thus, these publications should not be shared until their conversion is complete.
sources.Progress string The current conversion progress. During the Preview stage, it has a range of [0..1], which indicates the stage completion percentage. On the L1 stage, it shows the number of completed pages.

# 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
Name Description
Path id REQUIRED Publication identifier.
Path sourceId REQUIRED Source identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
source object
source.id string Source's unique identifier. Although these IDs are unique across the system, they cannot be used without a publication identifier.
source.publicationId string Parent publication identifier.
source.links array A set of HATEOAS links.
source.links.rel string The kind of relation with the linked resource.
source.links.type string The HTTP method to use with this link.
source.links.href string Link URL.
source.state string The processing state of the source file. It can be one of the following values: WaitAutoQueue - source file upload was completed, but it is not queued for conversion yet; Queued - the source file is in the conversion queue; Completed - the source file has been partially converted, publication preview is available; CompletedAllStages - the source file has been completely converted and was activated in the publication; CompletedWithErrors - there was a permanent error during conversion, re-uploading the same file will not fix it; WaitManualQueue - a special status, never set automatically, meaning the source file upload was completed, but it will not be put in the conversion queue.
source.stage string The current conversion state (if the source is still converting). At the moment, there are two stages: Preview and L1. After Preview is completed, the source will be activated for the publication only if it does not have any previous successful sources. Publication in the preview mode is customizable, the first few pages can be viewed, and other pages will load as the conversion completes. Preview publications are not optimized for end users, and thus, these publications should not be shared until their conversion is complete.
source.Progress string The current conversion progress. During the Preview stage, it has a range of [0..1], which indicates the stage completion percentage. On the L1 stage, it shows the number of completed pages.

# 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.

WARNING

If url or data contain invalid values (inaccessible URL, not a PDF file, PDF exceeding limitations), the source is marked as erroneous and, if it was the only source, the publication itself gets deleted.

# Parameters in path and query
Name Description
Path id REQUIRED Publication identifier.
# Parameters in request body
Name Type Description
filename string The name of your PDF file.
url string The URL of the PDF file that will be used to create the source for the publication. The URL must be publicly accessible for at least for several minutes. The server will follow HTTP redirects, however, when it encounters any kind of HTTP 200 response, it will download the file and and use it as PDF content disregarding the Content-Type headers.
data string Base64-encoded PDF file content that will be used to create the source for the publication.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string The created source's identifier.

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.

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
Name Description
Query title Link filter. In order to match, the tracked link's title must contain the exact title value.
Query publication-hashid Link filter. In order to match, the parent publication must have its URL identifier matching the publication-hashid value.
Query publication-uid Link filter. In order to match, the parent publication must have its unique identifier matching the publication-uid value.
Query publication-url Link filter. In order to match, the parent publication URL must exactly match the publication-url value.
Query count The number of links to return. Defaults to 10.
Query offset The starting number of links to return. Defaults to 0.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer The total number of links matching your request (disregarding offset/count).
userTotal integer The total number of links in your account (disregarding filters/offset/count).
links array A list of links matching your filters.
links.id string Link's unique identifier.
links.title string Link title (visible only to the link owner, not to end-users).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there are some new statistics collected for the link which you haven't seen via your account (views via API do not count); WithoutNewData - there are no 'unseen' statistics for the link; Active - the link is active and enabled; Deleted - the link was deleted and unavailable to end-users (readers); Expired - the link's lifetime has ended since it was not clicked on before the set expiration time.
links.createdAt string Link creation timestamp, ISO 8601 date format.
links.urlName string The unique URL part of the link. To get the full URL, you should prefix it with https://online.flippingbook.com/link/ (for the default domain).
links.triggerId string Trigger identifier for the link.
links.shortStats object View statistics for the link.
links.shortStats.fullStats object Statistics for the tracked link.
links.shortStats.fullStats.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.fullStats.viewDuration number Total viewing time (seconds).
links.shortStats.fullStats.visits number Total number of views.
links.shortStats.sinceLastUpdate object Statistics for the tracked link.
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.sinceLastUpdate.viewDuration number Total viewing time (seconds).
links.shortStats.sinceLastUpdate.visits number Total number of views.
links.publication object Parent publication excerpt.
links.publication.id object Parent publication identifiers.
links.publication.id.id string Parent publication's unique identifier.
links.publication.id.hashId string Parent publication's URL identifier.
links.publication.title string Parent publication's name.
links.publication.url string Parent publication's canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object The view trigger for the link.
links.triggers.onView.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onView.amount number The number of times that this trigger is allowed to fire.
links.triggers.onDownload object The download trigger for the link.
links.triggers.onDownload.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil object 'Link not opened before a set date' trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil.until string When this trigger should fire.
links.triggers.triggerVia string Trigger delivery method. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.

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

# Parameters in path and query
Name Description
Path linkId REQUIRED Tracked link identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer The total number of links matching your request (one).
userTotal integer The total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link's unique identifier.
links.title string Link title (visible only to the link owner, not to end-users).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there are some new statistics collected for the link which you haven't seen via your account (views via API do not count); WithoutNewData - there are no 'unseen' statistics for the link; Active - the link is active and enabled; Deleted - the link was deleted and unavailable to end-users (readers); Expired - the link's lifetime has ended since it was not clicked on before the set expiration time.
links.createdAt string Link creation timestamp, ISO 8601 date format.
links.urlName string The unique URL part of the link. To get the full URL, you should prefix it with https://online.flippingbook.com/link/ (for the default domain).
links.triggerId string Trigger identifier for the link.
links.shortStats object View statistics for the link.
links.shortStats.fullStats object Statistics for the tracked link.
links.shortStats.fullStats.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.fullStats.viewDuration number Total viewing time (seconds).
links.shortStats.fullStats.visits number Total number of views.
links.shortStats.sinceLastUpdate object Statistics for the tracked link.
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.sinceLastUpdate.viewDuration number Total viewing time (seconds).
links.shortStats.sinceLastUpdate.visits number Total number of views.
links.publication object Parent publication excerpt.
links.publication.id object Parent publication identifiers.
links.publication.id.id string Parent publication's unique identifier.
links.publication.id.hashId string Parent publication's URL identifier.
links.publication.title string Parent publication's name.
links.publication.url string Parent publication's canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object The view trigger for the link.
links.triggers.onView.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onView.amount number The number of times that this trigger is allowed to fire.
links.triggers.onDownload object The download trigger for the link.
links.triggers.onDownload.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil object 'Link not opened before a set date' trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil.until string When this trigger should fire.
links.triggers.triggerVia string Trigger delivery method. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.

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
Name Type Description
title string The tracked link's title (visible only to link owner, not to end-users).
publicationUid string Publication's unique identifier for the created link.
publicationHashId string Publication's URL identifier for the created link.
publicationUrl string Publication URL for the created link.
notificationType string Notification delivery method for link events. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.
onViewTriggerSingle boolean Whether a notification should be delivered when the link is opened for the first time.
onViewTrigger boolean Whether a notification should be delivered when the link is opened for the first 10 times.
onDownload boolean Whether a notification should be delivered when PDF print or download is requested for the linked publication.
onNotOpenedUntil boolean Whether a notification should be delivered when the link is not opened until the specified date/time (ISO 8601 format).
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer The total number of links matching your request (one).
userTotal integer The total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link's unique identifier.
links.title string Link title (visible only to the link owner, not to end-users).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there are some new statistics collected for the link which you haven't seen via your account (views via API do not count); WithoutNewData - there are no 'unseen' statistics for the link; Active - the link is active and enabled; Deleted - the link was deleted and unavailable to end-users (readers); Expired - the link's lifetime has ended since it was not clicked on before the set expiration time.
links.createdAt string Link creation timestamp, ISO 8601 date format.
links.urlName string The unique URL part of the link. To get the full URL, you should prefix it with https://online.flippingbook.com/link/ (for the default domain).
links.triggerId string Trigger identifier for the link.
links.shortStats object View statistics for the link.
links.shortStats.fullStats object Statistics for the tracked link.
links.shortStats.fullStats.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.fullStats.viewDuration number Total viewing time (seconds).
links.shortStats.fullStats.visits number Total number of views.
links.shortStats.sinceLastUpdate object Statistics for the tracked link.
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.sinceLastUpdate.viewDuration number Total viewing time (seconds).
links.shortStats.sinceLastUpdate.visits number Total number of views.
links.publication object Parent publication excerpt.
links.publication.id object Parent publication identifiers.
links.publication.id.id string Parent publication's unique identifier.
links.publication.id.hashId string Parent publication's URL identifier.
links.publication.title string Parent publication's name.
links.publication.url string Parent publication's canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object The view trigger for the link.
links.triggers.onView.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onView.amount number The number of times that this trigger is allowed to fire.
links.triggers.onDownload object The download trigger for the link.
links.triggers.onDownload.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil object 'Link not opened before a set date' trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil.until string When this trigger should fire.
links.triggers.triggerVia string Trigger delivery method. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.

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

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

WARNING

Updates do not reset tracked link event counters, thus, disabling and then re-enabling an event for the link will not trigger it again if it has happened before.

# Parameters in request body
Name Type Description
title string The tracked link's title (visible only to link owner, not to end-users).
publicationUid string Publication's unique identifier for the created link.
publicationHashid string Publication's URL identifier for the created link.
publicationUrl string Publication URL for the created link.
newState string An action to change the link state. Can be one of the following values: None (or null/unset) - do not change the link state; Disable - immediately disable the link; Enable - re-enable a previously disabled link; Delete - mark the link as deleted. Deleted links cannot be restored and are not accounted towards your account's limits.
notificationType string Method for delivering notification on link events. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.
onViewTriggerSingle boolean Whether a notification should be delivered when the link is opened for the first time.
onViewTrigger boolean Whether a notification should be delivered when the link is opened for the first 10 times.
onDownload boolean Whether a notification should be delivered when PDF print or download is requested for the linked publication.
onNotOpenedUntil boolean Whether a notification should be delivered when the link is not opened until the specified date/time (ISO 8601 format).
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer The total number of links matching your request (one).
userTotal integer The total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link's unique identifier.
links.title string Link title (visible only to the link owner, not to end-users).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there are some new statistics collected for the link which you haven't seen via your account (views via API do not count); WithoutNewData - there are no 'unseen' statistics for the link; Active - the link is active and enabled; Deleted - the link was deleted and unavailable to end-users (readers); Expired - the link's lifetime has ended since it was not clicked on before the set expiration time.
links.createdAt string Link creation timestamp, ISO 8601 date format.
links.urlName string The unique URL part of the link. To get the full URL, you should prefix it with https://online.flippingbook.com/link/ (for the default domain).
links.triggerId string Trigger identifier for the link.
links.shortStats object View statistics for the link.
links.shortStats.fullStats object Statistics for the tracked link.
links.shortStats.fullStats.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.fullStats.viewDuration number Total viewing time (seconds).
links.shortStats.fullStats.visits number Total number of views.
links.shortStats.sinceLastUpdate object Statistics for the tracked link.
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of the last view, ISO 8601 format.
links.shortStats.sinceLastUpdate.viewDuration number Total viewing time (seconds).
links.shortStats.sinceLastUpdate.visits number Total number of views.
links.publication object Parent publication excerpt.
links.publication.id object Parent publication identifiers.
links.publication.id.id string Parent publication's unique identifier.
links.publication.id.hashId string Parent publication's URL identifier.
links.publication.title string Parent publication's name.
links.publication.url string Parent publication's canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object The view trigger for the link.
links.triggers.onView.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onView.amount number The number of times that this trigger is allowed to fire.
links.triggers.onDownload object The download trigger for the link.
links.triggers.onDownload.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil object 'Link not opened before a set date' trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Indicates whether this trigger is enabled.
links.triggers.onNotOpenedUntil.until string When this trigger should fire.
links.triggers.triggerVia string Trigger delivery method. Can be one of the following values: Email - notify via email; Zapier - notify via Zapier/API (opens new window) integration.

# 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
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
customDomainsEnabled boolean Whether custom domains are available to the current user.
customDomains array List of custom domain names.

# 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 the trigger scope (limitTo), events, and an endpoint.

# Parameters in request body
Name Type Description
trigger object
trigger.triggerOn array Trigger scope (publication or trackedlink). All triggers should be bound to a publication or a tracked link.
trigger.events array A list of events that should cause the trigger to fire.
trigger.endpoint string The endpoint of a webhook to call upon firing the trigger. When it is called, trigger data and fire context are POSTed to your hook.
trigger.limitTo object Trigger scope. Can be null - in this case, the trigger should fire for specified events for all publications/tracked links in your account.
trigger.limitTo.parentObject string The scope of the trigger.
trigger.limitTo.parentObjectId string
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Created trigger's identifier.

# 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.

WARNING

Do not try to update triggers that are generated automatically. Only use this method to update the triggers you�ve created yourself.

# Parameters in path and query
Name Description
Path id REQUIRED Trigger identifier.
# Parameters in request body
Name Type Description
trigger object
trigger.triggerOn array Trigger scope (publication or trackedlink). All triggers should be bound to a publication or a tracked link.
trigger.events array A list of events that should cause the trigger to fire.
trigger.endpoint string The endpoint of a webhook to call upon firing the trigger. When it is called, trigger data and fire context are POSTed to your hook.
trigger.limitTo object Trigger scope. Can be null - in this case, the trigger should fire for specified events for all publications/tracked links in your account.
trigger.limitTo.parentObject string The scope of the trigger.
trigger.limitTo.parentObjectId string
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Updated trigger's identifier.

# 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
Name Description
Path id REQUIRED Trigger identifier.
# Response format
Name Type Description
success boolean Indicates whether your request was successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Deleted trigger's identifier.

# Event Names

Event Name Scope Description
lead Account, Publication A reader filled out the lead form in a publication.
session Account, Publication, Link A publication/tracked link view session has started. Note that for tracked links, the session event will only fire for the first ten opens.
notViewedUntil Account, Publication, Link A tracked link was not viewed in the specified time window.
print Account, Publication The print button in a publication has been clicked.
created Account A publication was created successfully (its first source has converted).
updated Account A publication was updated successfully (its subsequent source has converted).
deleted Account A publication was deleted.
convertationFailed Account A publication's conversion failed.
link Account, Publication A link in a publication was clicked.