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. Section General Information is about common concepts and how our APIs are organized. Sections about Key Management API and FlippingBook Online API provide product-specific information.

A FlippingBook app is a service that converts the client's PDFs into interactive digital documents.

# FlippingBook Public APIs General Information

There are several Public APIs available to your applications. They are all available 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 it may be changed in the future.

API requests and responses must be in UTF-8 encoded JSON format regardless of request's Content-Type, Accept-Charset and Accept HTTP headers. Requests may be in 'relaxed' JSON format, so single quotes may be used and property names are not required to be quoted. On the response side, there would always be Content-Type: application/json header and 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 HTTP bearer scheme, so all your requests (unless specified explicitly in request description) should come with the Authorization HTTP header with proper value:

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

# API Keys

You may receive your API key (linked to your FlippingBook account) by contacting our support team. Or, if you want to save the hassle just log into your account, go to https://logon.flippingbook.com/myaccesstoken, save the value of the AccessToken property and then call Key Management API new key method.

API keys are linked to your FlippingBook account and all actions are recorded/audited. No account may have more than 10 API keys.

# 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 general status of the API call, whether is has succeeded or not. In most case it is enough to handle only cases with success == true and ignore/throw errors when success == false.

The error and errors properties are mutually exclusive and contain one or many error objects (description follows). Although errors may contain zero or one error object.

Every single error object has the following structure:

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

Here the wellKnownError and errorCode are machine-readable error codes, and the message is for human use.

# HTTP Status Mapping

Although error/success state may be easily read from the response body the HTTP status is used to indicate success too. Successful calls should end with 200 OK status, and unsuccessful ones would have 4xx or 5xx errors.

# Universal Errors Codes

Most error codes are application/call specific, however, some universally returnable codes exist:

HTTP Status Code Error code Meaning
400 InvalidData The request body cannot be parsed as JSON.
401 NoAuthorizationHeader Your request does not include Authorization HTTP header.
401 BadAuthorizationType 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 calls our API too fast and has exceeded the rate limit.
500 InternalError Your request does not meet required format or some internal error has occurred.

# API Usage Limits

To prevent abuse API usage is limited in several ways:

  • Request Rate Limiting
  • General API limitations
  • Domain-specific API limitations

# Request Rate Limiting

Each API key is allowed to make one request per second with bursts (consequent requests without any delay) up to ten requests. After the burst, the next one is available after ten seconds of inactivity (or even more if you keep your request rate under one per second).

# General API Limitations

API keys are linked to your FlippingBook account. For each account, there may be no more than ten keys.

# Domain-specific API Limitations

For every application domain (e.g. FlippingBook Online) there may be additionally enforced limits. Access to API features may be limited by your purchased edition/plan and various limits on entities are enforced. Consult each application API documentation for the details.

# API Changes Policy

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

# Key Management API

This API is used to control your API keys. Using it you may issue new keys, 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 in your account, including the one you're using to call it.

# Parameters in path and query
Name Description
Query accessToken This parameter is required only if you omit Authorization HTTP header as a fallback authentication method. Value of accessToken is a session access token from FlippingBook single sign-on service and could be obtained by visiting https://logon.flippingbook.com/myaccesstoken while logged in to FlippingBook account (opens new window).
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
keys array 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 HTTP Bearer authorization scheme with an existing API key or with session access token from FlippingBook single sign-on service.

# Parameters in request body
Name Type Description
accessToken string This parameter is required only if you omit Authorization HTTP header as a fallback authentication method. Value of accessToken is a session access token from FlippingBook single sign-on service and could be obtained by visiting https://logon.flippingbook.com/myaccesstoken while logged in to FlippingBook account (opens new window).
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
key string Newly created key for accessing your account via API.

# Revoke an existing API key

DELETE /api/v1/auth/key

This method irreversibly deletes currently used API key.

# Response format
Name Type Description
success boolean Indicates if your request has been 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 build of one or more Source entities. The source represents one publication version and usually corresponds to one source PDF file. Each publication may contain zero or many Tracked/Individual Links entities that represent a special type of links to a publication with independent tracking, statistics, and notifications.

If your account gives you an option for a custom domain and you have at least one set up, then each of your publications must be assigned to these Custom Domain entities.

To make the integration to external systems easier there is Triggers/hooks system.

To allow simpler API exploration most entities contain HATEOAS (opens new window) links.

# The Publication Entity

Publications are the main entity of FlippingBok Online. They serve as an entry point for end-users (readers) and represent a document available online with defined behavior and looks. Yet it is not enough to just create a publication, your application 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 the list of all publications in your account.

TIP

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

# Parameters in path and query
Name Description
Query count Number of publications to return. Defaults to 10.
Query offset Starting number of publication to return. Defaults to 0.
Query query Publication filter. In order to match publication name must exactly contain query value.
Query hashid Publication filter. In order to match publication's identifier (the number in the publication URL) must exactly match hashid value.
Query url Publication filter. In order to match publication URL must exactly match url value.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer Total number of publications matching request (disregarding offset/count).
publications array Matching publications.
publications.id string Publication unique identifier. This one will never change whatever you do with the publication.
publications.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications it may change 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 Kind of relation with linked resource.
publications.links.type string 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 - publication was moved to trash, restoration possible; Deleted - publication was irreversibly deleted; CompletedAllStages - publication has at least one source that converted successfully; HasContent, Empty, Published - internally used statuses, do not rely on them.
publications.seoEnabled boolean Is SEO optimization enabled for the publication. That means web search indexing engines will see text content of your publication and is will appear in our sitemap.
publications.ownerHashId string Publication owner identifier. You would probably never need it.
publications.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing actual publication (when it is allowed by publication's security policy).
publications.canonicalLink string Canonical URL of the publication.
publications.totalPages integer Total number of pages in the publication. This will have valid value once the publication source has completely converted.
publications.lastPdfName string The filename of the latest uploaded PDF source file.
publications.customizationOptions object Publication looks & behavior settings.
publications.customizationOptions.password boolean Password for password-protected publications.
publications.customizationOptions.hardcoverEnabled boolean Is hardcover enabled for the publication.
publications.customizationOptions.companyLogoEnabled boolean Is company logo display enabled for the publications.
publications.customizationOptions.companyLogoUrl boolean URL which is open on company logo clicks.
publications.customizationOptions.rtlEnabled boolean Is publication in RTL mode (this is designed for Hebrew and Arabic publications, where page flipping direction and controls layout must be reversed).
publications.customizationOptions.theme string Selected skin for the publication.

# Retrieve information about one 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 The publication identifier.
# Response format
Name Type Description
success boolean Indicates if your request has been 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 unique identifier. This one will never change whatever you do with the publication.
publication.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications it may change 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 Kind of relation with linked resource.
publication.links.type string 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 - publication was moved to trash, restoration possible; Deleted - publication was irreversibly deleted; CompletedAllStages - publication has at least one source that converted successfully; HasContent, Empty, Published - internally used statuses, do not rely on them.
publication.seoEnabled boolean Is SEO optimization enabled for the publication. That means web search indexing engines will see text content of your publication and is will appear in our sitemap.
publication.ownerHashId string Publication owner identifier. You would probably never need it.
publication.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing actual publication (when it is allowed by publication's security policy).
publication.canonicalLink string Canonical URL of the publication.
publication.totalPages integer Total number of pages in the publication. This will have valid value once the publication source has completely converted.
publication.lastPdfName string The filename of the latest uploaded PDF source file.
publication.customizationOptions object Publication looks & behavior settings.
publication.customizationOptions.password boolean Password for password-protected publications.
publication.customizationOptions.hardcoverEnabled boolean Is hardcover enabled for the publication.
publication.customizationOptions.companyLogoEnabled boolean Is company logo display enabled for the publications.
publication.customizationOptions.companyLogoUrl boolean URL which is open on company logo clicks.
publication.customizationOptions.rtlEnabled boolean Is publication in RTL mode (this is designed for Hebrew and Arabic publications, where page flipping direction and controls layout must be reversed).
publication.customizationOptions.theme string Selected skin for the publication.

# Create a new publication possibly attaching new source file.

POST /api/v1/fbonline/publication

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

TIP

In case when url or data is specified, the Source entity is created implicitly.

WARNING

If url or data contain invalid value (inaccessible URL, not a PDF file, PDF exceeding limitations), 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 existing publication name is left unchanged.
description string Publication description. When omitted existing publication description is left unchanged.
folder string Folder id for the publication. When folder id is omitted, then the publication's folder is left unchanged. When it is set to null, the publication is moved to the Home folder.
domain string Domain for the publication. When domain is omitted, then the publication's domain is left unchanged. When your account does not have custom domains then the domain should be omitted.
filename string The name of your PDF file.
url string The URL of PDF file to create source for the publication from. URL must be publicly accessible at least for several minutes.
data string Base64 encoded PDF file content to create source for the publication from.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Unque publication identifier.
hashId string Publication identifier for use in URLs.
url string Canonical publication URL.
links array A set of HATEOAS links.
links.rel string Kind of relation with linked resource.
links.type string HTTP method to use with this link.
links.href string Link URL.
lastModified string Publication last modification date.
createdSource object
createdSource.success boolean Indicates if your request has been 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 was specified in the request.
createdSource.id string Created source's identifier.

# Update metadata of one publication possibly attaching new source file.

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

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

TIP

In case when url or data is specified, the Source entity is created implicitly.

WARNING

If url or data contain invalid value (inaccessible URL, not a PDF file, PDF exceeding limitations), 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 The publication identifier.
# Parameters in request body
Name Type Description
name string Publication name. When omitted existing publication name is left unchanged.
description string Publication description. When omitted existing publication description is left unchanged.
folder string Folder id for the publication. When omitted existing publication folder is left unchanged. When set to null, publication is moved to the Home folder.
domain string Domain for the publication. When omitted existing publication domain is left unchanged. Should be omitted when your account does not have custom domains.
filename string The name of your PDF file.
url string The URL of PDF file to create source for the publication from. URL must be publicly accessible at least for several minutes.
data string Base64 encoded PDF file content to create source for the publication from.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Unque publication identifier.
hashId string Publication identifier for use in URLs.
url string Canonical publication URL.
links array A set of HATEOAS links.
links.rel string Kind of relation with linked resource.
links.type string HTTP method to use with this link.
links.href string Link URL.
lastModified string Publication last modification date.
createdSource object
createdSource.success boolean Indicates if your request has been 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 was specified in the request.
createdSource.id string Created source's identifier.

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

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

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

WARNING

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

# Parameters in path and query
Name Description
Path id REQUIRED The publication identifier.
# Parameters in request body
Name Type Description
hardCover boolean Should hard cover be enabled for the publication.
setPasswordProtection string How publication password protection should be handled. keep to keep existing configuration; disable to remove password protection; manual - specify password in the manualPassword parameter; numeric to generate random password containing only digits; auto to generate random password.
manualPassword string Password to set for the publication.
generatePasswordLength string The length of the generated random password.
logoUrl string New URL for the company logo.
enableRtl string Set the publication RTL mode.
theme string Set the publication theme.
# Response format
Name Type Description
success boolean Indicates if your request has been 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 unique identifier. This one will never change whatever you do with the publication.
publication.hashId string Publication identifier for URLs. Although it is automatically assigned to all publications it may change 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 Kind of relation with linked resource.
publication.links.type string 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 - publication was moved to trash, restoration possible; Deleted - publication was irreversibly deleted; CompletedAllStages - publication has at least one source that converted successfully; HasContent, Empty, Published - internally used statuses, do not rely on them.
publication.seoEnabled boolean Is SEO optimization enabled for the publication. That means web search indexing engines will see text content of your publication and is will appear in our sitemap.
publication.ownerHashId string Publication owner identifier. You would probably never need it.
publication.contentRoot string Base URL for all publication assets. Files there are not public, so you cannot access them without viewing actual publication (when it is allowed by publication's security policy).
publication.canonicalLink string Canonical URL of the publication.
publication.totalPages integer Total number of pages in the publication. This will have valid value once the publication source has completely converted.
publication.lastPdfName string The filename of the latest uploaded PDF source file.
publication.customizationOptions object Publication looks & behavior settings.
publication.customizationOptions.password boolean Password for password-protected publications.
publication.customizationOptions.hardcoverEnabled boolean Is hardcover enabled for the publication.
publication.customizationOptions.companyLogoEnabled boolean Is company logo display enabled for the publications.
publication.customizationOptions.companyLogoUrl boolean URL which is open on company logo clicks.
publication.customizationOptions.rtlEnabled boolean Is publication in RTL mode (this is designed for Hebrew and Arabic publications, where page flipping direction and controls layout must be reversed).
publication.customizationOptions.theme string Selected skin for the publication.

# Delete publication

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

With this method your application can mark publication for deletion.

TIP

Publications are not deleted immediately, instead they are put into '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 if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.

# The Source Entity

Publication sources represent the publication's content. More than one source may be added to each publication 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 must be not password-protected and does not contain XFA (forms). There's a limit on PDF file size (500Mb) and amount of pages (2000).

WARNING

Once created, sources cannot be updated and/or deleted. On creation, they are put into conversion queue and activated (so the publication displays it) when conversion finished.

# List all sources for the given publication

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

This method allows your application to retireve the history of sources for the given publication. Although sources cannot be modified once created it may be desirable to check how many versions publication have and from which PDFs they were created.

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

# Retrieve information about one 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 watch for source conversion progress.

# Parameters in path and query
Name Description
Path id REQUIRED The publication identifier.
Path sourceId REQUIRED The source identifier.
# Response format
Name Type Description
success boolean Indicates if your request has been 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 unique identifier. Although these ids are unique across the system they cannot be used without publication identifier.
source.publicationId string Parent publication identifier.
source.links array A set of HATEOAS links.
source.links.rel string Kind of relation with linked resource.
source.links.type string HTTP method to use with this link.
source.links.href string Link URL.
source.state string Processing state of the source file. It can be one of the following values: WaitAutoQueue - source file upload has completed yet it is not queued for conversion yet; Queued - source file is in conversion queue; Completed - source file has been converted partially, publication preview is available; CompletedAllStages - source file has been converted completely and it was activated in publication; CompletedWithErrors - there was a permanent error during conversion, re-uploading the same file will be fruitless; WaitManualQueue - special status meaning that source file has been uploaded yet it will not be put in conversion queue, this status is never set automatically.
source.stage string Current conversion state (if the source is still converting). At the moment there's two stages: Preview and L1. After the Preview is completed, the source is activated for the publication only if it does not have any previous successful sources. Publication in preview mode is customizable, several first pages are available for viewing and other pages are loaded as they completes. Preview publication content delivery to end users is not optimized and thus these publications should not be shared until they conversion is complete.
source.Progress string Current conversion progress. During Preview stage it has range [0..1] which means stage completion percentage, and on 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 source for the given publication. Source's PDF must be either base64 encoded and passed within request or (preferrably) made publicly available on the internet for several minutes and passed as URL.

WARNING

If url or data contain invalid value (inaccessible URL, not a PDF file, PDF exceeding limitations), 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 The publication identifier.
# Parameters in request body
Name Type Description
filename string The name of your PDF file.
url string The URL of PDF file to create source for the publication from. URL must be publicly accessible at least for several minutes. The server would follow HTTP redirects however when it encounter any HTTP 200 response it will download it and use as PDF content disregarding Content-Type headers.
data string Base64 encoded PDF file content to create source for the publication from.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Created source's identifier.

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

Each link has a separate object for handling its events called 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 list of tracked links in your account. Although tracked links are bound to publications they can be fetched in account context for all publications at once.

# Parameters in path and query
Name Description
Query title Link filter. In order to match tracked link title must exactly contain title value.
Query publication-hashid Link filter. In order to match parent publication must have its URL identifier matching publication-hashid value.
Query publication-uid Link filter. In order to match parent publication must have its unique identifier matching publication-uid value.
Query publication-url Link filter. In order to match parent publication URL must exactly match publication-url value.
Query count Number of links to return. Defaults to 10.
Query offset Starting number of link to return. Defaults to 0.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer Total number of links matching request (disregarding offset/count).
userTotal integer Total number of links in your account (disregarding filters/offset/count).
links array List of links matching your filter.
links.id string Link unique identifier.
links.title string Link title (visible only to link owner, not end-user).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there is some 'unseen' statistics collected for the link; WithoutNewData - there is no 'unseen' statistics for the link; Active - link is active and enabled; Deleted - link was deleted and unavailable to end-users (readers); Expired - link's lifetime ended - it was not clicked before set expiration time.
links.createdAt string Link creation timestamp. ISO 8601 date format.
links.urlName string Unique URL part for the link. To get 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 tracked link
links.shortStats.fullStats.lastViewedAt string Date/time of 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 tracked link
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of 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 unique identifier.
links.publication.id.hashId string Parent publication URL identifier.
links.publication.title string Parent publication name.
links.publication.url string Parent publication canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object View trigger for the link.
links.triggers.onView.enabled boolean Is this trigger enabled.
links.triggers.onView.amount number How many times this trigger is allowed to fire.
links.triggers.onDownload object Download trigger for the link.
links.triggers.onDownload.enabled boolean Is this trigger enabled.
links.triggers.onNotOpenedUntil object Link not opened before trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Is this trigger 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 (opens new window) integration.

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

# Parameters in path and query
Name Description
Path linkId REQUIRED The tracked link identifier.
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer Total number of links matching request (one).
userTotal integer Total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link unique identifier.
links.title string Link title (visible only to link owner, not end-user).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there is some 'unseen' statistics collected for the link; WithoutNewData - there is no 'unseen' statistics for the link; Active - link is active and enabled; Deleted - link was deleted and unavailable to end-users (readers); Expired - link's lifetime ended - it was not clicked before set expiration time.
links.createdAt string Link creation timestamp. ISO 8601 date format.
links.urlName string Unique URL part for the link. To get 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 tracked link
links.shortStats.fullStats.lastViewedAt string Date/time of 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 tracked link
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of 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 unique identifier.
links.publication.id.hashId string Parent publication URL identifier.
links.publication.title string Parent publication name.
links.publication.url string Parent publication canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object View trigger for the link.
links.triggers.onView.enabled boolean Is this trigger enabled.
links.triggers.onView.amount number How many times this trigger is allowed to fire.
links.triggers.onDownload object Download trigger for the link.
links.triggers.onDownload.enabled boolean Is this trigger enabled.
links.triggers.onNotOpenedUntil object Link not opened before trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Is this trigger 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 (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 Tracked link title visible only to owner.
publicationUid string Publication unique identifier for the created link.
publicationHashId string Publication URL identifier for the created link.
publicationUrl string Publication URL for the created link.
notificationType string Method for delivering notification on link events. Can be one of the following values: Email - notify via email; Zapier - notify via zapier (opens new window) integration.
onViewTriggerSingle boolean Should notification be delivered when link is opened for the first time?
onViewTrigger boolean Should notification be delivered when link is opened (first 10 times)?
onDownload boolean Should notification be delivered when PDF download or printing is requested for linked publication?
onNotOpenedUntil boolean Should notification be delivered when link is not opened until specified date/time (ISO 8601 format)?
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer Total number of links matching request (one).
userTotal integer Total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link unique identifier.
links.title string Link title (visible only to link owner, not end-user).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there is some 'unseen' statistics collected for the link; WithoutNewData - there is no 'unseen' statistics for the link; Active - link is active and enabled; Deleted - link was deleted and unavailable to end-users (readers); Expired - link's lifetime ended - it was not clicked before set expiration time.
links.createdAt string Link creation timestamp. ISO 8601 date format.
links.urlName string Unique URL part for the link. To get 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 tracked link
links.shortStats.fullStats.lastViewedAt string Date/time of 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 tracked link
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of 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 unique identifier.
links.publication.id.hashId string Parent publication URL identifier.
links.publication.title string Parent publication name.
links.publication.url string Parent publication canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object View trigger for the link.
links.triggers.onView.enabled boolean Is this trigger enabled.
links.triggers.onView.amount number How many times this trigger is allowed to fire.
links.triggers.onDownload object Download trigger for the link.
links.triggers.onDownload.enabled boolean Is this trigger enabled.
links.triggers.onNotOpenedUntil object Link not opened before trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Is this trigger 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 (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 some event for the link will not cause to trigger it again if it happened before.

# Parameters in request body
Name Type Description
title string Tracked link title visible only to owner.
publicationUid string Publication unique identifier for the created link.
publicationHashid string Publication URL identifier for the created link.
publicationUrl string Publication URL for the created link.
newState string Change link state. Can be one of the following values: None (or null/unset) - do not change link state; Disable - immediately disable link; Enable - re-enable previously disabled link; Delete - mark link as deleted. Deleted links cannot be restored and are not accounted toward 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 (opens new window) integration.
onViewTriggerSingle boolean Should notification be delivered when link is opened for the first time?
onViewTrigger boolean Should notification be delivered when link is opened (first 10 times)?
onDownload boolean Should notification be delivered when PDF download or printing is requested for linked publication?
onNotOpenedUntil boolean Should notification be delivered when link is not opened until specified date/time (ISO 8601 format)?
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
total integer Total number of links matching request (one).
userTotal integer Total number of links in your account (disregarding filters/offset/count).
links array One link matching your request.
links.id string Link unique identifier.
links.title string Link title (visible only to link owner, not end-user).
links.state string Link state. It may consist of any combination (comma separated) of the following values: WithNewData - there is some 'unseen' statistics collected for the link; WithoutNewData - there is no 'unseen' statistics for the link; Active - link is active and enabled; Deleted - link was deleted and unavailable to end-users (readers); Expired - link's lifetime ended - it was not clicked before set expiration time.
links.createdAt string Link creation timestamp. ISO 8601 date format.
links.urlName string Unique URL part for the link. To get 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 tracked link
links.shortStats.fullStats.lastViewedAt string Date/time of 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 tracked link
links.shortStats.sinceLastUpdate.lastViewedAt string Date/time of 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 unique identifier.
links.publication.id.hashId string Parent publication URL identifier.
links.publication.title string Parent publication name.
links.publication.url string Parent publication canonical URL.
links.triggers object Triggers for the link.
links.triggers.onView object View trigger for the link.
links.triggers.onView.enabled boolean Is this trigger enabled.
links.triggers.onView.amount number How many times this trigger is allowed to fire.
links.triggers.onDownload object Download trigger for the link.
links.triggers.onDownload.enabled boolean Is this trigger enabled.
links.triggers.onNotOpenedUntil object Link not opened before trigger for the link.
links.triggers.onNotOpenedUntil.enabled boolean Is this trigger 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 (opens new window) integration.

# The Custom Domain Entity

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

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

# List 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 if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
customDomainsEnabled boolean Custom domains 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 could manage custom triggers with event trigger API.

# Create a new trigger

POST /api/v1/fbonline/triggers

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

# Parameters in request body
Name Type Description
trigger object
trigger.triggerOn array Trigger scope type. All triggers should be bound to publication or tracked link.
trigger.events array List of events for which the trigger shoud fire.
trigger.endpoint string Endpoint of 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 trigger should fire for specified events for all books/tracked links in your account.
trigger.limitTo.parentObject string Scope type of the trigger.
trigger.limitTo.parentObjectId string
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Created trigger identifier.

# Update the trigger

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

With this method your application may modify the trigger. Either events for which the trigger is fired or webhook address could be modified.

# Parameters in path and query
Name Description
Path id REQUIRED The trigger identifier.
# Parameters in request body
Name Type Description
trigger object
trigger.triggerOn array Trigger scope type. All triggers should be bound to publication or tracked link.
trigger.events array List of events for which the trigger shoud fire.
trigger.endpoint string Endpoint of 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 trigger should fire for specified events for all books/tracked links in your account.
trigger.limitTo.parentObject string Scope type of the trigger.
trigger.limitTo.parentObjectId string
# Response format
Name Type Description
success boolean Indicates if your request has been successful or not.
wellKnownError string Machine-readable error code.
message string Human-readable error message.
error string Detailed error code.
id string Updated trigger identifier.

# Delete the trigger

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

With this method your application may delete trigger by its identifier. After deletion the trigger will be fired no more neither it will be accounted towards account limit.

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

# Event Names

Event Name Scope Description
lead Account, Publication Lead form in the publication has been passed.
session Account, Publication, Link Publication/tracked link view session started.
notViewedUntil Account, Publication, Link Tracked link was not viewed in the specified time window.
print Account, Publication Print button in the publication has been clicked.
created Account Publication has been created successfully (first source converted).
updated Account Publication has been updated successfully (non-first source converted).
deleted Account Publication has been deleted.
convertationFailed Account Publication conversion failed.
link Account, Publication Link in the publication has been clicked.