developers();
Get started
Client libraries
Accounts
Folders
Publications
Publishing
Subscribers
Subscribers DRM
Response object
Sorting
Error codes

Get started

How do I get my API key?

Our API is a feature exclusive to our PREMIUM and PLATINUM users. If you are a BASIC user and wish to benefit from this feature, please upgrade.

 

Go to the Settings page of your account and click on API Keys on the left hand side.

Click on NEW API KEY.

In the window that opens, select the rights for this API key.

Once you have selected the desired options, click CREATE API KEY to finish the process.

Where can I find my public key and secret key?

Go to the Settings page of your account and click on API Keys on the left hand side.

Click on your API key.

In the window that opens, you have access to your public and private (secret) key. You will need both to communicate with the API.

Endpoints

There are 2 endpoints:
  • Generic endpoint: https://api.calameo.com/1.0
  • Upload endpoint: https://upload.calameo.com/1.0

Limits

The following restrictions apply to our API:
  • A maximum of 10,000 requests per hour
  • A maximum of 10 documents published every 15 minutes

Methods

Accounts

Action Description
getAccountInfos Get information on your account
fetchAccountSubscriptions Fetch the folders of your account
fetchAccountBooks Fetch the publications of your account
fetchAccountSubscribers Fetch the subscribers of your account

Folders

Action Description
getSubscriptionInfos Get information on a folder
fetchSubscriptionBooks Fetch the publications of a folder
fetchSubscriptionSubscribers Fetch the subscribers of a folder

Publications

Action Description
getBookInfos Get information on a publication
activateBook Activate a publication
deactivateBook Deactivate a publication
updateBook Update a publication's properties
deleteBook Permanently delete a publication
fetchBookTocs Fetch a publication's table of contents
fetchBookComments Fetch the comments of a publication
renewBookPrivateUrl Change the private URL of a private publication

Publishing

Action Description
publish Publish a document
publishFromUrl Publish a document from a URL
publishFromText Publish a document from plain text
revise Upload a new version of an existing publication
reviseFromUrl Upload a new version of an existing publication from a URL
reviseFromText Upload a new version of an existing publication from plain text

Subscribers

Action Description
getSubscriberInfos Get information on a subscriber
activateSubscriber Activate a subscriber
deactivateSubscriber Deactivate a subscriber
addSubscriber Add a new subscriber to a folder
updateSubscriber Update a subscriber's properties
deleteSubscriber Permanently delete a subscriber
fetchSubscriberBooks Fetch a subscriber's publications
authSubscriberSession Authenticate a subscriber login/password and create a subscriber session
checkSubscriberSession Validate a subscriber session
deleteSubscriberSession Terminate a subscriber session

Subscriber DRMs

Action Description
fetchSubscriberDRMSingles Fetch the Single DRMs of a subscriber
fetchSubscriberDRMPeriods Fetch the Period DRMs of a subscriber
fetchSubscriberDRMSeries Fetch the Series DRMs of a subscriber
addSubscriberDRMSingle Add a new Single DRM to a subscriber
addSubscriberDRMPeriod Add a new Period DRM to a subscriber
addSubscriberDRMSerie Add a new Series DRM to a subscriber
updateSubscriberDRMPeriod Update an existing Period DRM of a subscriber
updateSubscriberDRMSerie Update an existing Series DRM of a subscriber
deleteSubscriberDRMSingle Permanently delete a Single DRM of a subscriber
deleteSubscriberDRMPeriod Permanently delete a Period DRM of a subscriber
deleteSubscriberDRMSerie Permanently delete a Series DRM of a subscriber
clearSubscriberDRMs Permanently delete all DRMs of a subscriber

How to sign your requests ?

For security and authentication, the Calaméo API requires each request to be signed.

The steps to sign a request

  1. Sort the request parameters alphabetically
  2. Concatenate your API private (secret) key and the request's parameters key / value pairs
  3. Calculate the MD5 hash of this concatenated string
  4. Include the signature parameter in the request with this MD5 hash as value

Example request

Here are the public and secret keys we will use:

Public key  84c92f2c5686d350d3d2d15c2073ec23
Private (secret) key  1jHj0HORiWhpmw9QqOXsLoZjweVm7BWoT5WPWC2AbFsuWl95

In this example, we are going to list our account publications. The following parameters will be used:

apikey  84c92f2c5686d350d3d2d15c2073ec23
action  API.fetchAccountBooks
output  JSON

To calculate the signature of this request, we concatenate the API secret key with the name-value alphabetically sorted parameters:

1jHj0HORiWhpmw9QqOXsLoZjweVm7BWoT5WPWC2AbFsuWl95actionAPI.fetchAccountBooksapikey84c92f2c5686d350d3d2d15c2073ec23outputJSON

We get the MD5 hash of this string:

C867521B01925CE79E16FD630F2BE646

The complete request looks like this:

https://api.calameo.com/1.0?apikey=84c92f2c5686d350d3d2d15c2073ec23&action=API.fetchAccountBooks&output=JSON&signature=C867521B01925CE79E16FD630F2BE646

Client libraries

Node.js

There is an SDK written for NodeJs that can facilitate working with this API:

https://github.com/fadomire/calameo-node-sdk

Accounts

getAccountInfos

This action allows you to recover information about your account.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP

Response

This method returns an account.

Name Type Description
ID Account's ID
Name Account's name
City Town/city of the account
Country Country of the account, using the official two-letter code format
WebsiteName Name of the website
WebsiteUrl Address of the website
PublicUrl Public URL of the account

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "7MPmsP",
      "requests": 159,
      "content": {
         "ID": 4516825,
         "Name": "api",
         "Type": "",
         "City": "",
         "Country": "FR",
         "Description": "",
         "WebsiteName": "",
         "WebsiteUrl": "",
         "PublicUrl": "https://www.calameo.com/accounts/4516825",
         "ThumbUrl": "",
         "PictureUrl": ""
      }
   }
};

fetchAccountSubscriptions

This action allows you to recover all or part of the Folders belonging to your account.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
order String of characters used to define the organization criteria of the folders (see Sorting folders)
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of folders. Default is 0
step Number of folders to be sent from the start position (max: 50)

Response

This method returns an array of Folders.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "EGNNi2",
      "requests": 162,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": [
            {
               "ID": 4540112,
               "AccountID": 4516825,
               "Name": "Mon dossier",
               "Description": "",
               "Books": 0,
               "Subscribers": 0,
               "Creation": "2015-10-06 16:55:39",
               "Modification": "2015-10-06 16:55:39",
               "PublicUrl": "https://www.calameo.com/subscriptions/4540112"
            }
         ]
      }
   }
};

fetchAccountBooks

This action allows you to fetch your account's publications.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
order String of characters used to define the organization criteria of the publications (see Sorting publication)
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of publications. Default is 0
step Number of publications to be sent from the start position (max: 50)

Response

This method returns an array of Publications.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "GNnIiZ",
      "requests": 210,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": [
            {
               "ID": "0045168254f0132f6cf5f",
               "SubscriptionID": 4540112,
               "AccountID": 4516825,
               "Name": "Guided Tour EN",
               "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
               "Category": "MISC",
               "Format": "MISC",
               "Dialect": "en",
               "Status": "DONE",
               "IsPublished": 1,
               "IsPrivate": 1,
               "AuthID": "dXT0xqsM5qjx",
               "AllowMini": 1,
               "Date": "2015-10-16",
               "Pages": 12,
               "Width": 595,
               "Height": 841,
               "Views": 0,
               "Downloads": 0,
               "Comments": 0,
               "Favorites": 0,
               "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
               "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
               "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
               "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
               "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
               "Creation": "2015-10-16 11:31:06",
               "Modification": "2015-10-16 11:31:51"
            }
         ]
      }
   }
};

fetchAccountSubscribers

This action allows you to fetch your account's subscribers.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
order String of characters used to define the organization criteria of the subscribers
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of subscribers. Default is 0
step Number of subscribers to be sent from the start position (max: 50)

Response

This method returns an array of Subscribers.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "NIwM0j",
      "requests": 163,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": [
            {
               "AccountID": 4516825,
               "SubscriptionID": 4540112,
               "LastName": "",
               "FirstName": "",
               "Email": "",
               "Login": "leia",
               "Password": "syCo3hJN",
               "IsActive": 0,
               "HasFullAccess": 0,
               "LastLogin": false,
               "Creation": "2015-10-16 11:31:05",
               "Modification": "2015-10-16 11:31:05",
               "Extras": ""
            }
         ]
      }
   }
};

Folders

getSubscriptionInfos

This action allows you to recover information about a Folder.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder

Response

This method returns a Folder.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "eK4YhB",
      "requests": 161,
      "content": {
         "ID": 4540112,
         "AccountID": 4516825,
         "Name": "Mon dossier",
         "Description": "",
         "Books": 0,
         "Subscribers": 0,
         "Creation": "2015-10-06 16:55:39",
         "Modification": "2015-10-06 16:55:39",
         "PublicUrl": "https://www.calameo.com/subscriptions/4540112"
      }
   }
};

fetchSubscriptionBooks

This action allows you to fetch a Folder's publications.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
order String of characters used to define the organization criteria of the publications (see Sorting publication)
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of publications. Default is 0
step Number of publications to be sent from the start position (max: 50)

Response

This method returns an array of Publications.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "ll7eoz",
      "requests": 209,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": [
            {
               "ID": "0045168254f0132f6cf5f",
               "SubscriptionID": 4540112,
               "AccountID": 4516825,
               "Name": "Guided Tour EN",
               "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
               "Category": "MISC",
               "Format": "MISC",
               "Dialect": "en",
               "Status": "DONE",
               "IsPublished": 1,
               "IsPrivate": 1,
               "AuthID": "dXT0xqsM5qjx",
               "AllowMini": 1,
               "Date": "2015-10-16",
               "Pages": 12,
               "Width": 595,
               "Height": 841,
               "Views": 0,
               "Downloads": 0,
               "Comments": 0,
               "Favorites": 0,
               "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
               "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
               "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
               "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
               "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
               "Creation": "2015-10-16 11:31:06",
               "Modification": "2015-10-16 11:31:51"
            }
         ]
      }
   }
};

fetchSubscriptionSubscribers

This action allows you to fetch a Folder's subscribers.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
order String of characters used to define the organization criteria of the subscribers (see Sorting subscriber)
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of subscribers. Default is 0
step Number of subscribers to be sent from the start position (max: 50)

Response

This method returns an array of Subscribers.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "munItu",
      "requests": 165,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": [
            {
               "AccountID": 4516825,
               "SubscriptionID": 4540112,
               "LastName": "",
               "FirstName": "",
               "Email": "",
               "Login": "leia",
               "Password": "syCo3hJN",
               "IsActive": 0,
               "HasFullAccess": 0,
               "LastLogin": false,
               "Creation": "2015-10-16 11:31:05",
               "Modification": "2015-10-16 11:31:05",
               "Extras": ""
            }
         ]
      }
   }
};

Publications

getBookInfos

This action allows you to recover information about a publication using its unique code.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "uTPuZE",
      "requests": 208,
      "content": {
         "ID": "0045168254f0132f6cf5f",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Guided Tour EN",
         "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "en",
         "Status": "DONE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "dXT0xqsM5qjx",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 12,
         "Width": 595,
         "Height": 841,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
         "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
         "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
         "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
         "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
         "Creation": "2015-10-16 11:31:06",
         "Modification": "2015-10-16 11:31:51"
      }
   }
};

activateBook

This action allows you to activate a publication.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "VJKqEV",
      "requests": 202
   }
};

deactivateBook

This action allows you to deactivate a publication.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "5ihxZm",
      "requests": 199
   }
};

updateBook

This action allows you to update a publication's properties.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id Unique publication ID
name Title of the publication. If not present, the filename will be used
description Description of the publication. If not present, the first page's text will be used
date Date of the publication for DRM management (YYYY-MM-DD)
is_published Activation status. Either 0 (disabled) or 1 (enabled)
publishing_mode Access to the publication. Either 1 (public) or 2 (private)
publish_date Date and time (UTC) of the publication scheduled publishing (YYYY-MM-DD HH:MM:SS).
private_url Use a private URL. Either 0 (disabled) or 1 (enabled)
view Default viewing mode. Either book, slide, scroll
subscribe Allow subscribers' access. Either 0 (disabled) or 1 (enabled)
comment Comments behavior. Either 0 (disabled), 1 (moderate all) or 4 (accept all)
download Download behavior. Either 0 (disabled) or 2 (everyone)
print Print behavior. Either 0 (disabled) or 2 (everyone)
share NEW Share menu. Either 0 (disabled), 1 (enabled). Enabled by default
adult Restrict access to adults. Either 0 (no) or 1 (yes)
direction Reading direction. Either 0 (left-to-right) or 1 (right-to-left)
license License. Either <empty> (traditional copyright) or pd (public domain), by, by_nc, by_nc_nd, by_nc_sa, by_nd or by_sa (Creative Commons)
skin_url Custom skin URL. Must be an absolute URL
logo_url Custom logo URL. Must be an absolute URL
logo_link_url Custom logo link URL. Must be an absolute URL
background_url Custom background URL. Must be an absolute URL
music Background music mode. Either 0 (loop forever), 1 (play only once)
music_url Custom background music URL. Must be an absolute URL
sfx Play sound effects like page flipping. Either 0 (disabled) or 1 (enabled)
sfx_url Custom page flipping sound URL. Must be an absolute URL

Note: If any property is missing from the request, its value will not be updated.

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "lACcQM",
      "requests": 205,
      "content": {
         "ID": "0045168254f0132f6cf5f",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Guided Tour EN",
         "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "en",
         "Status": "DONE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "LTDf9GwGH9bl",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 12,
         "Width": 595,
         "Height": 841,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
         "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
         "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
         "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=LTDf9GwGH9bl",
         "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=LTDf9GwGH9bl",
         "Creation": "2015-10-16 11:31:06",
         "Modification": "2015-10-16 11:31:51"
      }
   }
};

deleteBook

This action allows you to delete a publication using its unique code.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication to delete

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "LAfdRB",
      "requests": 257
   }
};

fetchBookTocs

This action allows you to retrieve the table of contents of a publication.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication

Response

Returns an array of TOC items:

Name Type Description
Level Hierarchy level of the item. From 1 to the highest
Name Label of the item
PageNumber Page number linked to the item

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "tARK2K",
      "requests": 206,
      "content": {
         "total": 0,
         "items": []
      }
   }
};

fetchBookComments

This action allows you to get the comments of a publication.

The API key must have access rights to commons.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication
order String of characters used to define the organization criteria of the comments. Only Date is available for now
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of comments. Default is 0
step Number of comments to be sent from the start position (max: 50)

Response

Returns an array of comments:

Name Type Description
PosterID ID of the comment poster
PosterName Name of the comment poster
PosterPublicUrl Absolute URL for the comment poster's page
PosterThumbUrl Absolute URL for the comment poster's thumbnail
Date Date of the comment
Text Text of the comment

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "K2o07v",
      "requests": 207,
      "content": {
         "total": 0,
         "start": 0,
         "step": 10,
         "items": []
      }
   }
};

renewBookPrivateUrl

This action allows you to renew a publication's private URL using its unique code.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id Unique identifying key of the publication

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "psBMJA",
      "requests": 204,
      "content": {
         "ID": "0045168254f0132f6cf5f",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Guided Tour EN",
         "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "unknown",
         "Status": "DONE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "dXT0xqsM5qjx",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 12,
         "Width": 595,
         "Height": 841,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
         "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
         "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
         "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
         "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=dXT0xqsM5qjx",
         "Creation": "2015-10-16 11:31:06",
         "Modification": "2015-10-16 11:31:51"
      }
   }
};

Publishing

publish

This action allows you to publish a document.

The API key must have access rights to publish.

Requests must be multipart/form-data encoded.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
file Document to be uploaded (like provided by a HTML form file field)
subscription_id ID of the folder
name Title of the publication. If not present, the filename will be used
description Description of the publication. If not present, the first page's text will be used
date Date of the publication for DRM management (YYYY-MM-DD)
is_published Activation status. Either 0 (disabled) or 1 (enabled)
publishing_mode Access to the publication. Either 1 (public) or 2 (private)
publish_date Date and time (UTC) of the publication scheduled publishing (YYYY-MM-DD HH:MM:SS).
private_url Use a private URL. Either 0 (disabled) or 1 (enabled)
view Default viewing mode. Either book, slide, scroll
subscribe Allow subscribers' access. Either 0 (disabled) or 1 (enabled)
comment Comments behavior. Either 0 (disabled), 1 (moderate all) or 4 (accept all)
download Download behavior. Either 0 (disabled) or 2 (everyone)
print Print behavior. Either 0 (disabled) or 2 (everyone)
share Share menu. Either 0 (disabled), 1 (enabled). Enabled by default
adult Restrict access to adults. Either 0 (no) or 1 (yes)
direction Reading direction. Either 0 (left-to-right) or 1 (right-to-left)
license License. Either <empty> (traditional copyright) or pd (public domain), by, by_nc, by_nc_nd, by_nc_sa, by_nd or by_sa (Creative Commons)
skin_url Custom skin URL. Must be an absolute URL
logo_url Custom logo URL. Must be an absolute URL
logo_link_url Custom logo link URL. Must be an absolute URL
background_url Custom background URL. Must be an absolute URL
music Background music mode. Either 0 (loop forever), 1 (play only once)
music_url Custom background music URL. Must be an absolute URL
sfx Play sound effects like page flipping. Either 0 (disabled) or 1 (enabled)
sfx_url Custom page flipping sound URL. Must be an absolute URL

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "qOSFby",
      "requests": 175,
      "content": {
         "ID": "0045168254f0132f6cf5f",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Guided Tour EN",
         "Description": "",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "unknown",
         "Status": "",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "LTDf9GwGH9bl",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:31:06",
         "Modification": "2015-10-16 11:31:06"
      }
   }
};

publishFromUrl

This action allows you to publish a document directly from the URL on the Internet.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
url URL of the document to publish
subscription_id ID of the folder
name Title of the publication. If not present, the filename will be used
description Description of the publication. If not present, the first page's text will be used
date Date of the publication for DRM management (YYYY-MM-DD)
is_published Activation status. Either 0 (disabled) or 1 (enabled)
publishing_mode Access to the publication. Either 1 (public) or 2 (private)
publish_date Date and time (UTC) of the publication scheduled publishing (YYYY-MM-DD HH:MM:SS).
private_url Use a private URL. Either 0 (disabled) or 1 (enabled)
view Default viewing mode. Either book, slide, scroll
subscribe Allow subscribers' access. Either 0 (disabled) or 1 (enabled)
comment Comments behavior. Either 0 (disabled), 1 (moderate all) or 4 (accept all)
download Download behavior. Either 0 (disabled) or 2 (everyone)
print Print behavior. Either 0 (disabled) or 2 (everyone)
share Share menu. Either 0 (disabled), 1 (enabled). Enabled by default
adult Restrict access to adults. Either 0 (no) or 1 (yes)
direction Reading direction. Either 0 (left-to-right) or 1 (right-to-left "manga mode")
license License. Either <empty> (traditionnal copyright) or pd (public domain), by, by_nc, by_nc_nd, by_nc_sa, by_nd or by_sa (Creative Commons)
skin_url Custom skin URL. Must be an absolute URL
logo_url Custom logo URL. Must be an absolute URL
logo_link_url Custom logo link URL. Must be an absolute URL
background_url Custom background URL. Must be an absolute URL
music Background music mode. Either 0 (loop forever), 1 (play only once)
music_url Custom background music URL. Must be an absolute URL
sfx Play sound effects like page flipping. Either 0 (disabled) or 1 (enabled)
sfx_url Custom page flipping sound URL. Must be an absolute URL

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "yRc9GZ",
      "requests": 214,
      "content": {
         "ID": "004516825ca65f113d232",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Test",
         "Description": "",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "unknown",
         "Status": "",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "nl85OHvgXeKP",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:31:52",
         "Modification": "2015-10-16 11:31:52"
      }
   }
};

publishFromText

This action allows you to publish a document from plain text.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
text Text to use as the document content
subscription_id ID of the folder
name Title of the publication. If not present, the filename will be used
description Description of the publication. If not present, the first page's text will be used
date Date of the publication for DRM management (YYYY-MM-DD)
is_published Activation status. Either 0 (disabled) or 1 (enabled)
publishing_mode Access to the publication. Either 1 (public) or 2 (private)
publish_date Date and time (UTC) of the publication scheduled publishing (YYYY-MM-DD HH:MM:SS).
private_url Use a private URL. Either 0 (disabled) or 1 (enabled)
view Default viewing mode. Either book, slide, scroll
subscribe Allow subscribers' access. Either 0 (disabled) or 1 (enabled)
comment Comments behavior. Either 0 (disabled), 1 (moderate all) or 4 (accept all)
download Download behavior. Either 0 (disabled) or 2 (everyone)
print Print behavior. Either 0 (disabled) or 2 (everyone)
share Share menu. Either 0 (disabled), 1 (enabled). Enabled by default
adult Restrict access to adults. Either 0 (no) or 1 (yes)
direction Reading direction. Either 0 (left-to-right) or 1 (right-to-left)
license License. Either <empty> (traditional copyright) or pd (public domain), by, by_nc, by_nc_nd, by_nc_sa, by_nd or by_sa (Creative Commons)
skin_url Custom skin URL. Must be an absolute URL
logo_url Custom logo URL. Must be an absolute URL
logo_link_url Custom logo link URL. Must be an absolute URL
background_url Custom background URL. Must be an absolute URL
music Background music mode. Either 0 (loop forever), 1 (play only once)
music_url Custom background music URL. Must be an absolute URL
sfx Play sound effects like page flipping. Either 0 (disabled) or 1 (enabled)
sfx_url Custom page flipping sound URL. Must be an absolute URL

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "X9p0h2",
      "requests": 213,
      "content": {
         "ID": "0045168255f6738ad6193",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Book",
         "Description": "",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "unknown",
         "Status": "",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "ZuOoYt9jRzPo",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:31:51",
         "Modification": "2015-10-16 11:31:51"
      }
   }
};

revise

This action allows you to publish a new revision of a document.

The API key must have access rights to publish.

Requests must be multipart/form-data encoded.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication
file Document to be uploaded (like provided by a HTML form file field)

Response

This method returns a Publication.

Name Type Description
ID ID of the publication
AccountID Publication's owner account ID (should be your account ID)
SubscriptionID Publication's owner subscription ID
Name Title of the publication
Description Description of the publication
Status Conversion status of the publication. Either QUEUE (waiting to be converted), PROCESS (processing document), STORE (converting document), ERROR (error during conversion) or DONE (publication ready)
IsPublished Sends 1 if the publication is published and 0 if not
IsPrivate Sends 1 if the publication is private and 0 if not
AuthID Authentication parameter for private URLs (authid)
AllowMini Sends 1 if the publication allows access to the miniCalaméo and 0 if not
Pages Number of pages of the publication
Width Width of a page of the publication
Height Height of a page of the publication
Views Number of views of the publication
Downloads Number of downloads of the publication
Comments Number of comments of the publication
Favorites Number of favorites from the publication
Date Reference date of the publication
Creation Date of creation of the publication
Publication Scheduled date of the publication (UTC)
Modification Date of the last modification of the publication
PosterUrl Absolute URL for the publication's larger cover
PictureUrl Absolute URL for the publication's cover
ThumbUrl Absolute URL for the publication's thumbnail
PublicUrl Absolute URL for the publication's overview
ViewUrl Absolute URL for the publication's reading page

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "61uHfi",
      "requests": 219,
      "content": {
         "ID": "0045168254f0132f6cf5f",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Guided Tour EN",
         "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "en",
         "Status": "REQUEUE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "LTDf9GwGH9bl",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:31:53",
         "Modification": "2015-10-16 11:31:53"
      }
   }
};

reviseFromUrl

This action allows you to publish a new revision of document from a file available on the internet.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication
url URL of the document to publish
subscription_id ID of the folder

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "TrRptA",
      "requests": 227,
      "content": {
         "ID": "004516825ca65f113d232",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Test",
         "Description": "1",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "de",
         "Status": "REQUEUE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "nl85OHvgXeKP",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:31:58",
         "Modification": "2015-10-16 11:31:58"
      }
   }
};

reviseFromText

This action allows you to publish a new revision of a document from plain text.

The API key must have access rights to publish.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
book_id ID of the publication
text Text to use as the document content
subscription_id ID of the folder

Response

This method returns a Publication.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "qdinQy",
      "requests": 231,
      "content": {
         "ID": "0045168255f6738ad6193",
         "SubscriptionID": 4540112,
         "AccountID": 4516825,
         "Name": "Book",
         "Description": "Hello Mars ;)",
         "Category": "MISC",
         "Format": "MISC",
         "Dialect": "af",
         "Status": "REQUEUE",
         "IsPublished": 1,
         "IsPrivate": 1,
         "AuthID": "ZuOoYt9jRzPo",
         "AllowMini": 1,
         "Date": "2015-10-16",
         "Pages": 0,
         "Width": 0,
         "Height": 0,
         "Views": 0,
         "Downloads": 0,
         "Comments": 0,
         "Favorites": 0,
         "PosterUrl": "",
         "PictureUrl": "",
         "ThumbUrl": "",
         "PublicUrl": "",
         "ViewUrl": "",
         "Creation": "2015-10-16 11:32:00",
         "Modification": "2015-10-16 11:32:00"
      }
   }
};

Subscribers

getSubscriberInfos

This action allows you to get a subscriber's data.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This method returns a Subscriber.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "JuUmPb",
      "requests": 164,
      "content": {
         "AccountID": 4516825,
         "SubscriptionID": 4540112,
         "LastName": "",
         "FirstName": "",
         "Email": "",
         "Login": "leia",
         "Password": "syCo3hJN",
         "IsActive": 0,
         "HasFullAccess": 0,
         "LastLogin": false,
         "Creation": "2015-10-16 11:31:05",
         "Modification": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

activateSubscriber

This action allows to activate a deactivated subscriber.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "a5hfbL",
      "requests": 215
   }
};

deactivateSubscriber

This action allows to deactivate an activated subscriber. Once deactivated, the subscriber can no longer access their publications.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "gxcOoT",
      "requests": 211
   }
};

addSubscriber

This action allows you to add a subscriber.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Subscriber login (must be unique in a folder)
password Subscriber password (if empty an 8 character password will be generated)
lastname Subscriber last name
firstname Subscriber first name
email Subscriber e-mail
language Subscriber language. Either EN (default), FR, ES, DE, IT, PT, JP, CN, KR, RU
full_access Subscriber has access to all subscriber enabled private publications of the subscription. Either 0 (disabled) or 1 (enabled)
is_active Subscriber activation status. Either 0 (inactive) or 1 (active)
extras Free field up to 255 characters

Response

This method returns a Subscriber.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "mTE0c0",
      "requests": 160,
      "content": {
         "AccountID": 4516825,
         "SubscriptionID": 4540112,
         "LastName": "",
         "FirstName": "",
         "Email": "",
         "Login": "leia",
         "Password": "syCo3hJN",
         "IsActive": 0,
         "HasFullAccess": 0,
         "LastLogin": false,
         "Creation": "2015-10-16 11:31:05",
         "Modification": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

updateSubscriber

This action allows you to update a subscriber.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Subscriber login (must be unique in a folder)
new_login New subscriber login (must be unique in a folder)
password New subscriber password
lastname Subscriber last name
firstname Subscriber first name
email Subscriber e-mail
language Subscriber language. Either EN (default), FR, ES, DE, IT, PT, JP, CN, KR, RU
full_access Subscriber has access to all subscriber enabled private publications of the subscription. Either 0 (disabled) or 1 (enabled)
is_active Subscriber activation status. Either 0 (inactive) or 1 (active)
extras Free field up to 255 characters

Response

This method returns a Subscriber.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "oZIxXN",
      "requests": 167,
      "content": {
         "AccountID": 4516825,
         "SubscriptionID": 4540112,
         "LastName": "",
         "FirstName": "",
         "Email": "",
         "Login": "leia",
         "Password": "syCo3hJN",
         "IsActive": 0,
         "HasFullAccess": 0,
         "LastLogin": false,
         "Creation": "2015-10-16 11:31:05",
         "Modification": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

deleteSubscriber

This action allows you to delete a subscriber.

The API key must have access rights to subscribers_delete.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber you wish to delete

Response

This request sends the character stringok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "v4sFws",
      "requests": 260
   }
};

fetchSubscriberBooks

This action allows you to fetch a subscriber's publications.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
order String of characters used to define the organization criteria of the publications
way String of characters used to define the sort order. Either UP (default) or DOWN
start Start position of the range of publications. Default is 0
step Number of publications to be sent from the start position (max: 50)

Response

This method returns an array of Publications.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "OGV2yY",
      "requests": 201,
      "content": {
         "total": 1,
         "start": 0,
         "step": 10,
         "items": []
      }
   }
};

authSubscriberSession

This action allows you to create a subscriber session to bypass the subscriber login panel when opening a publication.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
lifetime 14400 Session validity period in seconds

Response

This method returns a Subscriber Session.

Name Type Description
ID Unique session key
SubscriptionID Unique identifying key of the subscriber's folder
SubscriberLogin Login of the subscriber

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "YlZVnX",
      "requests": 216,
      "content": {
         "ID": "7a5ed85cc34e7f20e953c6a1fbdbd400",
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia"
      }
   }
};

checkSubscriberSession

This action allows you check the validity of a subscriber session.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
session_id Unique session key

Response

This method returns a Subscriber Session.

Name Type Description
ID Unique session key
SubscriptionID Unique identifying key of the subscriber's folder
SubscriberLogin Login of the subscriber

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "TyAOnC",
      "requests": 217,
      "content": {
         "ID": "7a5ed85cc34e7f20e953c6a1fbdbd400",
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia"
      }
   }
};

deleteSubscriberSession

This action allows you to destroy a subscriber session.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
session_id Unique session key

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "EZueGr",
      "requests": 218
   }
};

Subscribers DRM

fetchSubscriberDRMSingles

This action allows you to recover all the unit DRMs of a subscriber.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This method returns an array of unit DRMs.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
Book Publication
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "7LwQuB",
      "requests": 200,
      "content": {
         "total": 1,
         "items": [
            {
               "ID": 477963,
               "SubscriptionID": 4540112,
               "SubscriberLogin": "leia",
               "Book": {
                  "ID": "0045168254f0132f6cf5f",
                  "SubscriptionID": 4540112,
                  "AccountID": 4516825,
                  "Name": "Guided Tour EN",
                  "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
                  "Category": "MISC",
                  "Format": "MISC",
                  "Dialect": "en",
                  "Status": "DONE",
                  "IsPublished": 0,
                  "IsPrivate": 1,
                  "AuthID": "LTDf9GwGH9bl",
                  "AllowMini": 1,
                  "Date": "2015-10-16",
                  "Pages": 12,
                  "Width": 595,
                  "Height": 841,
                  "Views": 0,
                  "Downloads": 0,
                  "Comments": 0,
                  "Favorites": 0,
                  "PosterUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/large.jpg",
                  "PictureUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
                  "ThumbUrl": "https://i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
                  "PublicUrl": null,
                  "ViewUrl": null,
                  "Creation": "2015-10-16 11:31:06",
                  "Modification": "2015-10-16 11:31:51"
               },
               "Date": "2015-10-16 11:31:51",
               "Extras": ""
            }
         ]
      }
   }
};

fetchSubscriberDRMPeriods

This action allows you to recover all the period DRMs of a subscriber.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This method returns an array of period DRMs.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the period (YYYY-MM-DD)
To End date of the period (YYYY-MM-DD)
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "LGG53n",
      "requests": 171,
      "content": {
         "total": 1,
         "items": [
            {
               "ID": 77859,
               "SubscriptionID": 4540112,
               "SubscriberLogin": "leia",
               "From": "2015-09-01",
               "To": "2016-09-01",
               "Date": "2015-10-16 11:31:05",
               "Extras": ""
            }
         ]
      }
   }
};

fetchSubscriberDRMSeries

This action allows you to recover all the series DRMs of a subscriber.

The API key must have access rights to subscribers_read.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This method returns an array of series DRMs.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the series (YYYY-MM-DD)
Books Number of publications from the start date
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "xlV1H4",
      "requests": 169,
      "content": {
         "total": 1,
         "items": [
            {
               "ID": 4949,
               "SubscriptionID": 4540112,
               "SubscriberLogin": "leia",
               "From": "2015-09-01",
               "Books": 10,
               "Date": "2015-10-16 11:31:05",
               "Extras": ""
            }
         ]
      }
   }
};

addSubscriberDRMSingle

This action lets you allow a subscriber to access a specific publication.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
book_id Unique ID of the publication. Publication must be private with subscriber access authorized
extras Free field of up to 255 characters

Response

This method returns a unit DRM.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
Book Publication
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "KE5qpk",
      "requests": 198,
      "content": {
         "ID": 477963,
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia",
         "Book": {
            "ID": "0045168254f0132f6cf5f",
            "SubscriptionID": 4540112,
            "AccountID": 4516825,
            "Name": "Guided Tour EN",
            "Description": "www.calameo.com CALAMÉO GUIDED TOUR ENGLISH",
            "Category": "MISC",
            "Format": "MISC",
            "Dialect": "unknown",
            "Status": "DONE",
            "IsPublished": 1,
            "IsPrivate": 1,
            "AuthID": "LTDf9GwGH9bl",
            "AllowMini": 1,
            "Date": "2015-10-16",
            "Pages": 12,
            "Width": 595,
            "Height": 841,
            "Views": 0,
            "Downloads": 0,
            "Comments": 0,
            "Favorites": 0,
            "PictureUrl": "//i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/thumb.jpg",
            "ThumbUrl": "//i.calameoassets.com/151016113106-69d5960ce53f69b75910e802001e6adf/p1.jpg",
            "PublicUrl": "https://www.calameo.com/books/0045168254f0132f6cf5f?authid=LTDf9GwGH9bl",
            "ViewUrl": "https://www.calameo.com/read/0045168254f0132f6cf5f?authid=LTDf9GwGH9bl",
            "Creation": "2015-10-16 11:31:06",
            "Modification": "2015-10-16 11:31:51"
         },
         "Date": "2015-10-16 11:31:51",
         "Extras": ""
      }
   }
};

addSubscriberDRMPeriod

This action allows you to create an access to publications within a period of time.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
from Start date of the period (YYYY-MM-DD)
to End date of the period (YYYY-MM-DD)
extras Free field of up to 255 characters

Response

This method returns a period DRM.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the period (YYYY-MM-DD)
To End date of the period (YYYY-MM-DD)
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "Oui7af",
      "requests": 168,
      "content": {
         "ID": 77859,
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia",
         "From": "2015-09-01",
         "To": "2016-09-01",
         "Date": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

addSubscriberDRMSerie

This action allows you to create an access to a fixed number of publications starting from a specific date.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
from Start date of the period (YYYY-MM-DD)
books Number of publications from the start date
extras Free field of up to 255 characters

Response

This method returns a series DRM.

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the series (YYYY-MM-DD)
Books Number of publications from the start date
Extras Free field up to 255 characters

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "ocrBAf",
      "requests": 166,
      "content": {
         "ID": 4949,
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia",
         "From": "2015-09-01",
         "Books": 10,
         "Date": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

updateSubscriberDRMPeriod

This action allows you to update a period DRM.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
period_id ID of the subscription period
from Start date of the period (YYYY-MM-DD)
to End date of the period (YYYY-MM-DD)
extras Free field of up to 255 characters

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "ZsI6Aq",
      "requests": 172,
      "content": {
         "ID": 77859,
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia",
         "From": "2015-09-01",
         "To": "2016-09-01",
         "Date": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

updateSubscriberDRMSerie

This action allows you to delete a subscriber's series DRM.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
from Start date of the period (YYYY-MM-DD)
books Number of publications from the start date
extras Free field of up to 255 characters
serie_id ID of the series subscription

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "jhReaO",
      "requests": 170,
      "content": {
         "ID": 4949,
         "SubscriptionID": 4540112,
         "SubscriberLogin": "leia",
         "From": "2015-09-01",
         "Books": 10,
         "Date": "2015-10-16 11:31:05",
         "Extras": ""
      }
   }
};

deleteSubscriberDRMSingle

This action allows you to revoke a subscriber's access to a specific publication.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
book_id Unique ID of the publication

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "E1wXF6",
      "requests": 203
   }
};

deleteSubscriberDRMPeriod

This action allows you to delete a subscriber's period DRM.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
period_id ID of the subscription period

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "0vLVJb",
      "requests": 174
   }
};

deleteSubscriberDRMSerie

This action allows you to delete a subscriber's series DRM.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber
serie_id ID of the series subscription

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "dEI48O",
      "requests": 173
   }
};

clearSubscriberDRMs

This action allows you to revoke all the DRMs of a subscriber (unit, period and series). The subscriber itself is not deleted.

The API key must have access rights to subscribers_write.

Request

Name Type Description
apikey API public key
signature Signature of the request. See How To Sign Your Requests
expires UNIX timestamp for request expiration (GMT)
output Format of the response. Either XML (default), JSON or PHP
subscription_id ID of the folder
login Login of the subscriber

Response

This request sends the character string ok if successful.

Example response

JSON 


{
   "response": {
      "status": "ok",
      "version": 2,
      "requestid": "GSLuiT",
      "requests": 212
   }
};

Response object

Publication

Name Type Description
ID ID of the publication
AccountID Publication's owner account ID (should be your account ID)
SubscriptionID Publication's owner subscription ID
Name Title of the publication
Description Description of the publication
Status Conversion status of the publication. Either QUEUE (waiting to be converted), PROCESS (processing document), STORE (converting document), ERROR (error during conversion) or DONE (publication ready)
IsPublished Sends 1 if the publication is published and 0 if not
IsPrivate Sends 1 if the publication is private and 0 if not
AuthID Authentication parameter for private URLs (authid)
AllowMini Sends 1 if the publication allows access to the miniCalaméo and 0 if not
Pages Number of pages of the publication
Width Width of a page of the publication
Height Height of a page of the publication
Views Number of views of the publication
Downloads Number of downloads of the publication
Comments Number of comments of the publication
Favorites Number of favorites from the publication
Date Reference date of the publication
Creation Date of creation of the publication
Publication Scheduled date of the publication (UTC)
Modification Date of the last modification of the publication
PosterUrl Absolute URL for the publication's larger cover
PictureUrl Absolute URL for the publication's cover
ThumbUrl Absolute URL for the publication's thumbnail
PublicUrl Absolute URL for the publication's overview
ViewUrl Absolute URL for the publication's reading page

Subscriber

Name Type Description
AccountID Subscriber's owner account ID (should be your account ID)
SubscriptionID Subscriber's folder ID
LastName Last name of the subscriber
FirstName First name of the subscriber
Email Email address of the subscriber
Login Login of the subscriber
Password Password of the subscriber
IsActive Activation status of the subscriber. Either 1 (activated), 0 (deactivated)
HasFullAccess Full access to the subscription. Either 1 (activated), 0 (deactivated)
LastLogin Date of the subscriber's last login
Creation Date the subscriber was created
Modification Date the subscriber was last edited
Extras Additional information on the subscriber, in varchar format up to 255 characters in size

Folder

Name Type Description
ID Unique identifying key for the folder
AccountID Unique identifying key for the account of the folder
Name Title of the folder
Description Description of the folder
Books Available publications inside the folder
Subscribers Available subscribers inside the folder (only returned for your account's folder)
Creation Date of the folder's creation
Modification Date of the folder's last modification
PublicUrl Absolute URL for the folder's overview

Subscriber session

Name Type Description
ID Unique session key
SubscriptionID Unique identifying key of the subscriber's folder
SubscriberLogin Login of the subscriber

Subscribers DRM

Unit DRM

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
Book Publication
Extras Free field up to 255 characters

Period DRM

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the period (YYYY-MM-DD)
To End date of the period (YYYY-MM-DD)
Extras Free field up to 255 characters

Series DRM

Name Type Description
ID ID of the DRM
SubscriptionID ID of the folder
SubscriberLogin Login of the subscriber
From Start date of the series (YYYY-MM-DD)
Books Number of publications from the start date
Extras Free field up to 255 characters

Sorting

Publications

Parameter used to sort publications.

Name Description
Name Title of the publication
Pages Number of pages of the publication
Comments Number of comments on the publication
Views Number of times the publication was read
Date Date of publication
Creation Date of creation
Modification Date the publication was last modified

Folders

Parameter used to sort folders.

Name Description
Name Title of the publication
Creation Date of creation
Modification Date the folder was last modified

Subscribers

Parameter used to sort subscribers.

Name Description
FirstName First name of the subscriber
LastName Last name of the subscriber
Login Login of the subscriber
LastLogin Date of last login
Creation Date of creation
Modification Date the subscriber was last modified

Error Codes

9x Rate limiting errors

Code Message
99 Too many requests

1xx Authentication errors

Code Message
101 Invalid signature
102 Invalid endpoint
103 Invalid account type (a PREMIUM or PLATINUM account is required)
104 Invalid API key
105 Invalid account API key
106 Request expired
107 Access denied

2xx Account errors

Code Message
201 Unknown account id

3xx Request errors

Code Message
301 Unknown account login
302 Missing or incorrect parameter
303 Document upload spam error

4xx Subscription errors

Code Message
401 Unknown Folder ID

5xx Publication errors

Code Message
501 Unknown book ID
502 Book not activated
503 Publication is not private
504 Publication is not published
505 Publication is not revised
506 Publication is not updated
507 Publication is not deleted
509 Publication's private URL not renewed
511 Maximum number of private publications reached

6xx Subscriber errors

Code Message
601 Unknown subscriber ID
602 The subscriber has not been added
603 The subscriber has not been updated
604 The subscriber has not been activated
605 The subscriber has not been deactivated
606 The subscriber has not been unsubscribed
607 The subscriber has not been deleted
608 The subscriber session has not been created
609 The subscriber session has not been deleted
610 Unknown subscriber session ID
611 Maximum number of subscriber reached

8xx Subscriber DRM errors

Code Message
801 The unit subscription has not been added
802 The unit subscription has not been updated
803 The unit subscription has not been deleted
811 The period subscription has not been added
812 The period subscription has not been updated
813 The period subscription has not been deleted
821 The series subscription has not been added
822 The series subscription has not been updated
823 The series subscription has not been deleted

9xx Misc. errors

Code Message
901 The character string to be searched for cannot be blank
902 The subscriber login cannot be blank
903 This subscriber login already exists
904 Unknown unit subscriber for this publication
905 Unknown subscription period
906 Unknown subscription series
907 The publication’s circulation mode cannot be public

17xx Upload errors

Code Message
1710 Document denied
1711 Identical document already exists. A list of identical existing publication is provided in response.error.content.books.
1712 Request denied
1713 Request denied
1714 Too many publications already converting. Please try again in a moment
1715 Maximum number of private publications reached. Upgrade or contact us
1720 Document size exceeds maximum allowed size
1721 Maximum storage capacity reached. Upgrade or contact us
1722 Unsupported document type
1723 Document size exceeds maximum allowed size
1724 Document size exceeds maximum allowed size
1725 Document partially uploaded
1726 Document not uploaded
1727 Internal error
1728 Internal error
Back to Calaméo Contact us