CloudPublish API
The CloudPublish API is a REST-style interface to the CloudPublish platform, outputing data in JSON format. The purpose of the API is to allow a publisher to create a front-end to the CloudPublish system. The front-end can be as simple as a catalogue listing or as complex as an ecommerce book-store.
It is important to note a few things that the CloudPublish API does not do:
- There is no customer/user database provided, as such. It is expected that you maintain your own customer-facing systems / website, and then supply a unique customer identifier to the API when referring to a specific customer (e.g., retrieving subscription data for a customer). This identifier would typically be the same ID or unique customer number as used in your own customer account database, thereby enabling you to link records effectively.
- The batch processing of PDFs into ebooks is not done via the API, although you can check the progress of ebooks by using the BookGetAll and BookGet methods.
For more information, please see the CloudPublish support pages.
API Documentation
Connection and authentication
The CloudPublish API is a REST-style interface. Connecting to the API is accomplished by making a GET request to the CloudPublish endpoint.
Future versions will support POST for larger requests, but currently each request is limited to 255 characters via GET.
Requests are structured as follows:
http://api.cloudpublish.co.uk/?method=MethodName&args=param%3Dvalue%26param%3Dvalue&p=YYYYY&nonce=23asd3a2f5g&h=XXXXXXXXXXXXXXXX
- Endpoint: always the same
- Method: the method you want to call (see the further documentation below)
- Args: URL-encoded parameter string, in name=value pairs, delimited by ampersand. The required and optional parameters vary based on the method.
- Publisher UID: your unique publisher UID within CloudPublish.
- Nonce: A one-time, unique code such as the output generated by PHP’s uniqid() function.
- Signature: the value XXXXXXXXXXXXXXXX is the MD5 hash produced from the concatenation of the entire URL up to (but not including) &h= and your shared secret.
Your shared secret is a key (a string of characters) known to both CloudPublish and to you, and should be kept confidential.
The value for each parameter should be URL-encoded (e.g. via the PHP urlencode() function) prior to hashing.
The entire URL cannot be longer than 255 characters.
The order of these elements is important (i.e. it must be as above).
The authentication signature is an MD5 hash of the query string, not including the initial “?” or “&h=”, concatenated with your shared secret. For example, using PHP, the hash would be generated as follows:
$query = 'method=ImprintsGet&args=imprint%3DExample%20&p=12345&nonce='.urlencode(uniqid());
$hash = md5($query . $secret);
You would then complete the URL by adding on the hash as follows:
$url = 'http://api.cloudpublish.co.uk/?' . $query . '&hash=' . $hash;
Results format
Results in JSON format always include the following components:
- code
- 200 on success, 400 if the request was bad, 500 if there was an internal error
- message
- an appropriate message (e.g. descriptive error message)
- data
- a structured response (if required)
- time
- a timestamp for the response
Some methods allow alternative formats to be specified (e.g. CSV or MARC). These formats include only the data element of a corresponding JSON response, and will be empty if an error occurred.
Testing
/Test
Parameters
- test_parameter [optional]
- any value (string)
- format [optional] default: json
- json
- csv
Returns
- data
- test_response string
Description
Returns the value of test_parameter as test_response.
Typical use
This method is useful when testing that you have integrated the API successfully.
Catalogue: General
These methods are applicable to more than one type of item.
Get subjects data
/SubjectsGetAll
Parameters
- subject_field [optional] default: thema
- thema
- subject
- start_node [optional] default: (empty)
- subject code (string)
- item_type [optional] default: book
- book
- journal
- series*
- collection
- customer_ref [optional]
- identifier to restrict tree to subscribed items only (string)
- format [optional] default: json
- json
Returns
- data
- subject_code string
- heading_en string
- heading_de string
- heading_fr string
- count_total integer
- count_available integer
- num_subscribed* integer
Description
Returns metadata for all subjects in the catalogue.
The result field subject_code contain the value of the Thema or Subject field (depending on what is passed in the subject_field parameter), and the result field heading_en will contain the human-readable version (identical to Subject if the subject_field is Subject).
If specified, the start_node will return a tree starting at that point, rather than at the top / root level. This is mainly relevant for Thema subjects.
If the item_type is series, the tree for the books catalogue will be returned broken down by series (i.e., the number of series available in each subject/thema).
The customer_ref parameter causes the num_subscribed field of the returned data to be populated.
Expand a subject
/SubjectsExpand
Parameters
- thema [mandatory]
Returns
- data
- subjects complex
- subjects
- subject_code string
- heading_en string
- heading_de string
- heading_fr string
Description
Expands a single Thema code into human-friendly headings, starting at the top node and working down. For example, a thema of ABC will return expansions for A, AB, and ABC.
Catalogue: Books
A book typically represents a single ebook.
Get book data (all books)
/BookGetAll
Parameters
- availability [optional] default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- subscribed*
- format [optional] default: json
- json
- csv
- marc
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- customer_ref [optional*]
- identifier for customer subscribed to returned books (string)
- imprint [optional] default: (empty = all)
- semicolon-delimited list of imprints
- series [optional] default: (empty = all)
- semicolon-delimited list of series
- series_code [optional] default: (empty = all)
- semicolon-delimited list of series codes
- book_ids [optional] default: (empty = all)
- semicolon-delimited list of book IDs
- open_access [optional] default: (empty = any)
- boolean 1/0
- sort_by [optional] default: score
- item_id
- title
- date_published
- series_volume
- sort_order [optional] default: ascending for title and item_id, descending for date_published
- asc
- desc
- offset [optional] default: 0
- offset of returned data set
*customer_ref is mandatory if availability is subscribed
Returns
- data
- book_id integer
- title string
- subtitle string
- series string
- series_volume string
- series_code string
- authors string (delimited by semicolon)
- initial character
- edition string
- isbn string
- filename string
- thema_codes string
- thema_qualifiers string
- imprint string
- date_published date (YYYY-MM-DD)
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- cover_fullsize_url string (url)
- open_access integer (1 or 0)
- on_sale integer (1 or 0)
- available_online integer (1 or 0)
- available_download integer (1 or 0)
- withdrawn integer (1 or 0)
- unavailable integer (1 or 0)
- unprocessed integer (1 or 0)
- subscribed* integer (2, 1 or 0)
Note that the marc return format is more complete (i.e. MARC21) and is suitable for import into library systems.
Description
Returns metadata for your catalogue (or a subset based on availability) in the specified format.
Note that a maximum of 500 results is returned. You will need to use the offset parameter to access a greater number of records (e.g., offset=250 to get up to 500 results starting at the 251st result). However, there is no restriction when using the MARC output format.
Note that "unavailable" includes withdrawn books as well as those not on sale because they are not yet processed (i.e. "unprocessed").
If available_since and/or published_since is used, this returns matching books that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated (0 = no access, 1 = full access, 2 = partial access via chapter subscription). To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Typical use
This method could be used to return an overview list of catalogue items to which a customer might have access. It could also be used to return MARC data to a specialist user (e.g. a librarian). The available_since and/or published_since parameters could be used to set up new title notifications for your users.
Get book data (single book)
/BookGet
Parameters
- id [optional*]
- a book ID (integer)
- isbn [optional*]
- an isbn (string)
- customer_ref [optional]
- identifier for customer subscribed to returned books (string)
- format [optional] default: json
- json
- csv
- marc
*one (and only one) of these parameters must be supplied
Returns
- data
- book_id integer
- title string
- subtitle string
- publication_type string
- series string
- series_code string
- series_volume string
- initial character
- edition string
- edition_statement string
- language string
- authors authors (Lastname, F; Last, F)
- author_info string
- editors editors (Lastname, F; Last, F)
- doi string
- isbn string
- replaces_isbn string
- replaced_by_isbn string
- related_isbns string
- filename string
- thema_codes string
- thema_qualifiers string
- imprint string
- description string
- description_short string
- pages integer
- copyright_year date (YYYY)
- date_published date (YYYY-MM-DD)
- price_currency string
- price_individual float (2dp)
- price_institution float (2dp)
- date_added datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- cover_fullsize_url string (url)
- open_access integer (1 or 0)
- search_available integer (1 or 0)
- on_sale integer (1 or 0)
- availability_code string
- available_online integer (1 or 0)
- available_download integer (1 or 0)
- withdrawn integer (1 or 0)
- unavailable integer (1 or 0)
- unprocessed integer (1 or 0)
- subscribed* integer (1 or 0)
- num_chapters** integer
- num_collections*** integer
Description
Returns metadata for a single book. This returns more data than /BookGetAll.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
**This refers to the number of Chapter products relating to this Book.
***This refers to the number of collections of which this Book is a member.
Typical use
This method could be used to populate a page of details for a specific book.
Get Table of Contents (single book)
/BookGetTOC
Parameters
- id [optional*]
- a book ID (integer)
- isbn [optional*]
- an isbn (string)
- format [optional] default: json
- json
*one (and only one) of these parameters must be supplied
Returns
- data
- page_number integer
- title string
Description
Returns the TOC (Table of Contents) for a single book, in JSON format only. Each element of the TOC is represented by a toc_entry, which in turn contains page_number and title elements.
Typical use
This method could be used to retrieve the TOC after a page has loaded, to save time on the initial page load (important, as some TOCs can be very large).
Get citation for book(s)
/BookGetCitation
Parameters
- id [mandatory]
- a book ID (integer, comma-delimited string of integers for multiple IDs)
- style [optional] default: apa
- apa
- mla
- ama
- turabian
- chicago
- page_range_start [optional]
- first page if citing a page range or a single page (integer)
- page_range_end [optional]
- Last page if citing a page range (integer)
- chapter_title [optional]
- title of a chapter or article within the book (string)
- retrieved_from_url [optional]
- a url if the citation is to include "retrieved from ... on ..." (current date will be used)
- format [optional] default: json
- json
- csv
Returns
- data
- book_id integer
- style string
- citation string
Description
Returns a standardised citation for a book in one of the styles shown above, optionally for a single page or page range.
Get imprints data
/ImprintsGetAll
Parameters
- customer_ref [optional]
- (identifier to restrict to imprints of subscribed books only)
- format [optional] default: json
- json
- csv
Returns
- data
- name string
- num_on_sale integer
- num_available_online integer
- num_available_download integer
- num_withdrawn integer
- num_unavailable integer
- num_unprocessed integer
- num_subscribed* integer
Description
Returns metadata for all imprints in the catalogue.
*The customer_ref parameter causes the num_subscribed field of the returned data to be populated, and will restrict the imprints returned to only those of the books to which the specified customer is subscribed.
Get imprint details (single imprint)
/ImprintGet
Parameters
- imprint [mandatory]
- an imprint (string)
- customer_ref [optional]
- (identifier to restrict to imprints of subscribed books only)
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- format [optional] default: json
- json
- csv
Returns
- data
- (as for /BookGetAll)
Description
Returns a list of books matching a specific imprint, with the same data structure as /BookGetAll.
Get series data
/SeriesGetAll
Parameters
- customer_ref [optional]
- (identifier to restrict to series of subscribed books only)
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- format [optional] default: json
- json
- csv
Returns
- data
- name string
- num_on_sale integer
- num_available_online integer
- num_available_download integer
- num_withdrawn integer
- num_unavailable integer
- num_unprocessed integer
- num_subscribed* integer
Description
Returns metadata for all series in the catalogue.
*The customer_ref parameter causes the num_subscribed field of the returned data to be populated.
The thema parameter causes only the series matching the specified Thema to be returned.
Catalogue: Contributors
A contributor is either an author or an editor (or both). Authors are associated with books, chapters, and journal articles only. Editors are associated with books and journal issues only.
Get contributors data
/ContributorsGetAll
Parameters
- begins_with [optional] default: (empty = any)
- single character or string
- open_access [optional] default: (empty = any)
- boolean 1/0
- availability [optional] default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- item_type [optional] default: (empty)
- string (book|journal)
- role [optional] default: (empty)
- string (author|editor)
- format [optional] default: json
- json
- csv
Returns
- data
- name string
- roles string
- num_open_access integer
- num_on_sale integer
- num_books_on_sale integer
- num_journals_on_sale integer
- num_withdrawn integer
- num_unavailable integer
- num_unprocessed integer
Description
Returns metadata for all contributors in the catalogue, optionally restricting the list to just open_access contributors only, and/or to contributors of books or journals only by specifying item_type, and/or to authors/editors only by specifying the role.
Get contributor details (single contributor)
/ContributorGet
Parameters
- name [mandatory]
- an contributor (string)
- role [optional] default: (empty)
- string (author|editor)
- item_type [optional] default: (empty)
- string (book|journal)
- customer_ref [optional]
- (identifier to restrict to contributors of subscribed books only)
- open_access [optional] default: (empty = any)
- boolean 1/0
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- availability [optional] default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- format [optional] default: json
- json
- csv
Returns
- items
- (as for /BookGetAll)
- metadata
- contributor string
- contributor_variation string
- num_items integer
- num_books integer
- num_journals integer
- num_as_author integer
- num_as_editor integer
- is_author boolean 1/0
- is_editor boolean 1/0
Description
Returns a list of books (including chapters) or journals (articles and issues), according to the optional item_type and/or role, matching a specific contributor with the same data structure as /CustomerSubscriptionsGet.
The metadata section contains totals from the items section, based on the availability parameter supplied, and an indication of whether the contributor is present as an author, an editor, or both.
Get authors data [DEPRECATED]
/AuthorsGetAll [DEPRECATED]
Parameters
- open_access [optional] default: (empty = any)
- boolean 1/0
- availability [optional] default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- item_type [optional] default: (empty)
- string (book|journal)
- format [optional] default: json
- json
- csv
Returns
- data
- name string
- num_open_access integer
- num_on_sale integer
- num_available_online integer
- num_available_download integer
- num_withdrawn integer
- num_unavailable integer
- num_unprocessed integer
Description
This method is deprecated. Please use /ContributorsGetAll instead.
Returns metadata for all authors in the catalogue, optionally restricting the list to just open_access authors only, and/or to authors of books or journals only by specifying item_type.
Get author details (single author) [DEPRECATED]
/AuthorGet [DEPRECATED]
Parameters
- author [mandatory]
- an author (string)
- item_type [mandatory] default: book
- string (book|journal)
- customer_ref [optional]
- (identifier to restrict to authors of subscribed books only)
- open_access [optional] default: (empty = any)
- boolean 1/0
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- availability [optional] default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- format [optional] default: json
- json
- csv
Returns
- data
- (as for /BookGetAll)
Description
This method is deprecated. Please use /ContributorGet instead.
Returns a list of books (including chapters) or journals (articles), according to item_type, matching a specific author with the same data structure as /CustomerSubscriptionsGet.
Catalogue: Chapters
A chapter consists of a fragment of a book that is already in your catalogue, defined by a page range within that book. While books are added by sending ONIX metadata, chapters are created via the API. Chapters are currently only available via the online eReader.
Get chapter data (all chapters)
/ChaptersGetAll
Parameters
- availability [optional] default: all
- all
- on_sale
- withdrawn
- subscribed
- format [optional] default: json
- json
- csv
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- book_id [optional] default: (matches all books)
- book identifier, to return chapters from this book only
- chapter_ids [optional] default: (empty = all)
- semicolon-delimited list of chapter IDs
- open_access [optional] default: (empty = any)
- boolean 1/0
- customer_ref [optional]
- identifier for customer subscribed to returned chapters (string)
- offset [optional] default: 0
- offset of returned data set
Returns
- data
- chapter_id integer
- book_id integer
- title string
- authors string (delimited by semicolon)
- doi string
- thema_codes string
- thema_qualifiers string
- date_published date (YYYY-MM-DD)
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- cover_fullsize_url string (url)
- open_access integer (1 or 0)
- on_sale integer (1 or 0)
- withdrawn integer (1 or 0)
- unavailable integer (1 or 0)
- subscribed* integer (1 or 0)
Note that the marc return format is more complete (i.e. MARC21) and is suitable for import into library systems.
Description
Returns metadata for chapters in your catalogue (or a subset based on availability or book) in the specified format.
Note that a maximum of 500 results is returned. You will need to use the offset parameter to access a greater number of records (e.g., offset=250 to get up to 500 results starting at the 251st result). However, there is no restriction when using the MARC output format.
Note that "unavailable" includes withdrawn chapters as well as those not on sale because they are not yet processed (i.e. "unprocessed").
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Get chapter data (single chapter)
/ChapterGet
Parameters
- id [mandatory]
- a chapter ID (integer)
- customer_ref [optional]
- customer identifier (string)
- format [optional] default: json
- json
- csv
- marc
Returns
- data
- chapter_id integer
- book_id integer
- title string
- chapter_number integer
- start_page integer
- end_page integer
- language string
- authors authors (Lastname, F; Last, F)
- author_info string
- doi string
- thema_codes string
- thema_qualifiers string
- keywords string
- imprint string
- series string
- description string
- wordcount integer
- pages integer
- date_published date (YYYY-MM-DD)
- price_currency string
- price_individual float (2dp)
- price_institution float (2dp)
- date_added datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- open_access integer (1 or 0)
- on_sale integer (1 or 0)
- available_online integer (1 or 0)
- available_download integer (1 or 0)
- withdrawn integer (1 or 0)
- unavailable integer (1 or 0)
- unprocessed integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for a single chapter. This returns more data than /ChaptersGetAll.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Typical use
This method could be used to populate a page of details for a specific chapter.
Create a chapter
/ChapterCreate
Parameters
- book_id [mandatory]
- book identifier (integer)
- title [mandatory]
- chapter title (string)
- chapter_number [optional]
- chapter number within the book (integer)
- start_page [mandatory]
- first page of the chapter, within the book (integer)
- end_page [mandatory]
- last page of the chapter, within the book (integer)
- copy_metadata [optional, default: 0]
- whether to copy the metadata from the book; if copying, other metadata is ignored (boolean 1/0)
- language [optional]
- ISO 639-2 language code (string)
- authors [optional]
- Firstname, Initial delimited by semicolons (string)
- doi [optional]
- chapter DOI (string)
- thema_codes [optional]
- Thema subject codes, delimited by semicolons (string)
- thema_qualifiers [optional]
- Thema qualifiers, delimited by semicolons (string)
- subjects [optional]
- free-text subjects, delimited by semicolons (string)
- description [optional]
- description (string, HTML permitted)
- wordcount [optional]
- (integer)
- date_published [optional]
- (date YYYY-MM-DD)
- price_currency [optional]
- pricing currency (string, e.g. GBP)
- price_ind [optional]
- pricing for individuals (float, 2dp)
- price_inst [optional]
- pricing for institutions(float, 2dp)
- open_access [optional, default: 0]
- whether to allow Open Access (boolean 1/0)
- available [optional, default: 0]
- on sale and/or available to read (boolean 1/0)
- withdrawn [optional, default: 0]
- withdrawn from sale (boolean 1/0)
Returns
- data
- chapter_id integer
Description
This method creates a chapter.
The metadata can mostly be copied from the parent book (although a data link will not be maintained) by using copy_metadata=1
Update a chapter
/ChapterUpdate
Parameters
- chapter_id [mandatory]
- chapter identifier (integer)
- title [optional]
- chapter title (string)
- chapter_number [optional]
- chapter number within the book (integer)
- start_page [optional]
- first page of the chapter, within the book (integer)
- end_page [optional]
- last page of the chapter, within the book (integer)
- language [optional]
- ISO 639-2 language code (string)
- authors [optional]
- Firstname, Initial delimited by semicolons (string)
- doi [optional]
- chapter DOI (string)
- thema_codes [optional]
- Thema subject codes, delimited by semicolons (string)
- thema_qualifiers [optional]
- Thema qualifiers, delimited by semicolons (string)
- subjects [optional]
- free-text subjects, delimited by semicolons (string)
- description [optional]
- description (string, HTML permitted)
- wordcount [optional]
- (integer)
- date_published [optional]
- (date YYYY-MM-DD)
- price_currency [optional]
- pricing currency (string, e.g. GBP)
- price_ind [optional]
- pricing for individuals (float, 2dp)
- price_inst [optional]
- pricing for institutions(float, 2dp)
- open_access [optional, default: 0]
- whether to allow Open Access (boolean 1/0)
- available [optional, default: 0]
- on sale and/or available to read (boolean 1/0)
- withdrawn [optional, default: 0]
- withdrawn from sale (boolean 1/0)
Returns
- data
- chapter_id integer
Description
This method updates a chapter.
Delete a chapter
/ChapterDelete
Parameters
- chapter_id [mandatory]
- the chapter ID (integer)
Description
This method deletes a chapter, if the chapter is not used in a subscription, order, or transaction.
Catalogue: Journals
Journals are handled slightly differently to books. There are several levels in the structure:
- Journal: An entire publication. Does not exist as a readable item.
- Issue: A single issue of a Journal. Can exist as a readable item, or as a container for Articles.
- Article: A single article within a single Issue of a Journal. Can exist as a readable item or as a metadata container for use with Issue.
- Reference: A single reference or endnote, associated with a single Article.
Therefore, a Journal may have multiple Issues, each of which may have multiple Articles, each of which may have multiple References.
The corresponding files you upload depend on whether you want to provide access by issue, or by article, or both. In any case you will need to upload issues and/or articles with unique filenames.
Important: In order to ensure uniqueness of your filenames, you must incorporate an ISSN or other identifier unique to your organisation. For books, the ISBN system accomplishes this for you. We recommend naming files as follows:
- Issue: ISSNvolXissY.pdf (where X and Y are integers)
- Article: ISSNvolXissYpZ.pdf (where Z is the page number of the article)
Get journal data (all journals)
/JournalGetAll
Parameters
- format [optional] default: json
- json
- csv
- journal_ids [optional] default: (empty = all)
- semicolon-delimited list of journal IDs
- availability [optional] default: all
- all
- on_sale
- withdrawn
- subscribed
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- imprint [optional] default: (empty = all)
- semicolon-delimited list of imprints
- customer_ref [optional]
- identifier for customer subscribed to returned books (string)
- open_access [optional] default: (empty = any)
- boolean 1/0
- offset [optional] default: 0
- offset of returned data set
Returns
- data
- journal_id integer
- title string
- subtitle string
- code string
- issn string
- issn_linking string
- isbn string
- language string
- url string
- doi string
- subject string
- keywords string
- thema_codes string
- thema_qualifiers string
- imprint string
- admin_name string
- admin_email string
- editor_name string
- editor_email string
- editorial_board string
- place string
- address string
- country string
- publication_statement string
- description string
- open_access integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for your journals, or a subset based on selected parameters, in the specified format.
If available_since and/or published_since is used, this returns matching journals that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Get journal data (single journal)
/JournalGet
Parameters
- format [optional] default: json
- json
- csv
- id [optional*]
- a journal ID (integer)
- isbn [optional*]
- an isbn (string)
- issn [optional*]
- an issn (string)
- code [optional*]
- a publisher code (string)
- customer_ref [optional]
- (identifier for customer subscribed to returned journals)
Returns
- data
- journal_id integer
- title string
- subtitle string
- code string
- issn string
- issn_linking string
- isbn string
- language string
- url string
- doi string
- subject string
- keywords string
- thema_codes string
- thema_qualifiers string
- imprint string
- admin_name string
- admin_email string
- editor_name string
- editor_email string
- editorial_board string
- place string
- address string
- country string
- publication_statement string
- description string
- price_currency string
- price_individual float (2dp)
- price_institution float (2dp)
- open_access integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed** integer (1 or 0)
Description
Returns metadata for a single journal. This returns more data than /JournalGetAll, including links (by ID) to all issues and articles connected to the journal.
description may contain HTML.
*One (and only one) of these identifiers must be supplied.
**The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal.
Get journal volume data
/JournalVolumeGetAll
Parameters
- journal_id [mandatory]
- a journal ID (integer)
- availability [optional] default: all
- all
- on_sale
- withdrawn
- subscribed
- customer_ref [optional]
- identifier for customer subscribed to returned books (string)
- format [optional] default: json
- json
Returns
- data
- journal_id integer
- volume integer
- num_issues integer
- date_published date (YYYY-MM-DD)
- open_access integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for volumes in the specified journal.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Get journal issue data (all issues)
/JournalIssueGetAll
Parameters
- format [optional] default: json
- json
- csv
- availability [optional] default: all
- all
- on_sale
- withdrawn
- subscribed
- journal_id [optional]
- a journal ID (integer)
- journal_issue_ids [optional] default: (empty = all)
- semicolon-delimited list of journal issue IDs
- volume [optional, requires journal_id]
- a volume number (integer)
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- customer_ref [optional]
- identifier for customer subscribed to returned books (string)
- imprint [optional] default: (empty = all)
- semicolon-delimited list of imprints
- open_access [optional] default: (empty = any)
- boolean 1/0
- offset [optional] default: 0
- offset of returned data set
Returns
- data
- journal_issue_id integer
- journal_id integer
- volume integer
- issue integer
- title string
- subtitle string
- keywords string
- description string
- editors string
- language string
- url string
- isbn string
- doi string
- thema_codes string
- thema_qualifiers string
- subjects string
- pages integer
- start_page integer
- end_page integer
- front_matter_pages integer
- back_matter_pages integer
- wordcount integer
- date_published date (YYYY-MM-DD)
- filename string
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- open_access integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for journal issues, or a subset based on selected parameters, in the specified format.
If volume is used, then journal_id must also be specified. This returns all issues in the corresponding volume of that journal.
If available_since and/or published_since is used, this returns matching issues that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Get journal issue data (single issue)
/JournalIssueGet
Parameters
- format [optional] default: json
- json
- csv
- id [optional*]
- a journal issue ID (integer)
- isbn [optional*]
- an isbn (string)
- customer_ref [optional]
- (identifier for customer subscribed to returned issue)
Returns
- data
- journal_issue_id integer
- journal_id integer
- journal_title string
- volume integer
- issue integer
- title string
- subtitle string
- keywords string
- description string
- editors string
- language string
- url string
- isbn string
- doi string
- thema_codes string
- thema_qualifiers string
- subjects string
- pages integer
- start_page integer
- end_page integer
- front_matter_pages integer
- back_matter_pages integer
- wordcount integer
- date_published date (YYYY-MM-DD)
- filename string
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- price_currency string
- price_individual float (2dp)
- price_institution float (2dp)
- open_access integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for a single journal issue. This returns more data than /JournalIssueGetAll, including links (by ID) to all articles connected to the journal.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal issue.
Get journal article data (all articles)
/JournalArticleGetAll
Parameters
- format [optional] default: json
- json
- csv
- journal_id [optional]
- a journal ID (integer)
- journal_issue_id [optional]
- a journal issue ID (integer)
- journal_article_ids [optional] default: (empty = all)
- semicolon-delimited list of journal article IDs
- volume [optional, requires journal_id]
- a volume number (integer)
- issue [optional, requires journal_id]
- an issue number (integer)
- available_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- published_since [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- thema [optional] default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
- customer_ref [optional]
- identifier for customer subscribed to returned books (string)
- imprint [optional] default: (empty = all)
- semicolon-delimited list of imprints
- open_access [optional] default: (empty = any)
- boolean 1/0
- offset [optional] default: 0
- offset of returned data set
Returns
- data
- journal_article_id integer
- journal_issue_id integer
- journal_id integer
- volume integer
- issue integer
- original_page_number integer
- title string
- subtitle string
- abstract string
- language string
- authors string
- url string
- doi string
- thema_codes string
- thema_qualifiers string
- subjects string
- pages integer
- wordcount integer
- date_published date (YYYY-MM-DD)
- filename string
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- open_access integer (1 or 0)
- subscribed* integer (1 or 0)
Description
Returns metadata for journal articles, or a subset based on selected parameters, in the specified format.
If volume is used, then journal_id must also be specified. In turn, volume is required if issue is specified. This returns all articles in the corresponding volume / issue of that journal.
Alternatively, journal_issue_id can be specified to return all articles associated with that issue.
If available_since and/or published_since is used, this returns matching issues that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Get journal article data (single article)
/JournalArticleGet
Parameters
- format [optional] default: json
- json
- csv
- id [mandatory]
- a journal article ID (integer)
- customer_ref [optional]
- (identifier for customer subscribed to returned issue)
Returns
- data
- journal_issue_id integer
- journal_id integer
- journal_title string
- issue_id integer
- journal_issue_title string
- volume integer
- issue integer
- original_page_number integer
- start_page integer
- end_page integer
- title string
- subtitle string
- abstract string
- language string
- authors string
- url string
- doi string
- thema_codes string
- thema_qualifiers string
- subjects string
- keywords string
- pages integer
- front_matter_pages integer
- back_matter_pages integer
- wordcount integer
- date_published date (YYYY-MM-DD)
- filename string
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- price_currency string
- price_individual float (2dp)
- price_institution float (2dp)
- open_access integer (1 or 0)
- search_available integer (1 or 0)
- subscribed* integer (1 or 0)
- references:
- journal_reference_id integer
- label string
- note string
- source string
- patent string
- title string
- edition_statement string
- series string
- volume string
- issue integer
- first_page integer
- last_page integer
- authors string
- date_published date (YYYY-MM-DD)
- publisher string
- publisher_place string
- url string
- url_access_date datetime (YYYY-MM-DD HH:MM:SS)
Description
Returns metadata for a single journal article. This returns more data than /JournalArticleGetAll, including all references.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal issue.
Get a reference in citation format
/JournalReferenceGetCitation
Parameters
- format [optional] default: json
- json
- csv
- style [optional] default: apa
- apa
- mla
- ama
- turabian
- chicago
- id [mandatory]
- a journal reference ID (integer)
Returns
- data
- citation string
Description
Returns a citation for a specified reference in the specified style.
Get all articles by an author
/JournalArticleAuthorSearch
Parameters
- format [optional] default: json
- json
- csv
- author [mandatory]
- match [optional] default: substring
- substring
- exact
Returns
- data
- author string
- articles:
- article_id
Description
Searches for a specified author in journal articles. The author can be be matched as a substring or exact. In either case, the returned data will include the author as matched (possibly multiple times if different variations are matched).
Get all references to an author
/JournalReferenceAuthorSearch
Parameters
- format [optional] default: json
- json
- csv
- author [mandatory]
- match [optional] default: substring
- substring
- exact
Returns
- data
- author string
- references:
- reference_id
Description
Searches for a specified author in journal references. The author can be be matched as a substring or exact. In either case, the returned data will include the author as matched (possibly multiple times if different variations are matched).
Collections
Collections are simply groups of the same type of item. They are typically used to group items for sales purposes, e.g. by subject. A collection can contain items of one (and only one) of the following types:
- Books
- Journals (i.e. complete journals)
- Journal issues (i.e. single issues)
- Journal articles
Get collections data
/CollectionsGetAll
Parameters
- customer_ref [optional]
- (identifier to restrict to collections containing subscribed items only)
- type [optional] default: (empty)
- books
- journals
- journal_issues
- journal_articles
- status [optional] default: public
- public
- private
- any
- featured [optional] default: 1
- 1
- 0
- subject [optional]
- a subject
- item_id [optional]
- a single item ID (integer)
- item_type [optional*]
- a single item type (book|chapter|journal_issue|journal_article)
- format [optional] default: json
- json
- csv
*Required if item_id is supplied
Returns
- data
- collection_id integer
- code string
- name string
- type string
- slug string
- subjects string
- num_titles integer
- num_titles_available integer
- public integer (1 or 0)
- featured integer (1 or 0)
- description text
Description
Returns metadata for any collections you have created.
If type is specified, only collections of that type will be returned. Note that only collections marked "public" will be returned, unless status is set to "any".
The customer_ref parameter causes will restrict the collections returned to only those containing items to which the specified customer is subscribed.
If item_id and item_type are provided, this will limit the results to collections containing that item, taking into account any other parameters.
Get collection details (single collection)
/CollectionGet
Parameters
- id [optional*]
- a collection ID (integer)
- slug [optional*]
- a collection slug (string)
- code [optional*]
- a collection metadata code (string)
- customer_ref [optional]
- (identifier to populate subscribed field)
- format [optional] default: json
- json
- csv
- marc**
*one of these parameters must be supplied
**MARC-format output is currently only available for eBook collections
Returns
- data
- (see description)
Description
Returns a list of titles matching a specific collection with the same data structure as /BookGetAll, /JournalGetAll, /JournalIssueGetAll, or JournalArticleGetAll depending on collection type.
The customer_ref parameter causes will cause the "subscribed" field of the results to be populated.
Accessing items for reading
Items can be accessed for online reading (using CloudPublish CloudReader) for download (PDF via Adobe Digital Editions with Adobe CRM).
Access an item (download or online)
/Read
Parameters
- book_id [optional*]
- a book ID (integer)
- journal_issue_id [optional*]
- a journal issue ID (integer)
- journal_article_id [optional*]
- a journal article ID (integer)
- chapter_id [optional*]
- a chapter ID (integer)
- customer_ref [mandatory unless in preview mode] default: (empty)
- a customer identifier (string)
- customer_user_ref [optional] default: (empty)
- a customer personalisation identifier (string)
- mode [mandatory]
- preview
- online
- download
- start_page [optional] default: 1
- a page to start reading (integer)
- return_url [optional] default: (see description)
- an encoded/escaped url to which the user will return after reading online
- drm [optional]
- soft
- hard
- access_token [optional] default: (empty)
- an access token code (string)
Returns
- url string
Description
This method allows items to be accessed for online reading in FastReader. This method returns a URL which can then be called, for a limited period, to either open FastReader (for online viewing) or to initiate a download.
*One (and only one) item ID must be supplied, either book_id, journal_issue_id, journal_article_id or chapter_id.
The customer_ref is required unless in preview mode. When the returned URL is used, the customer will be checked for a valid subscription and against the number of current readers.
The customer_user_ref is optional, and allows you to personalise content, by having more than one possible user per customer_ref. For example, if customer_ref refers to an organisation, then customer_user_ref can refer to a specific user within that organisation. If you do not include it, all personalisation data will be stored with the customer_ref alone. Therefore if there are multiple end-users sharing the same customer_ref, they will see each other's personalised content (bookmarks, notes, etc.), which is undesirable.
The preview mode provides a limited version of the item (online only), and does not cause a check against the number of current readers.
The return_url is the URL to which the user will be returned when they click "Exit" from FastReader (when reading online). If not provided, the publisher's default URL will be used (this can be changed in the publisher's settings).
Important: If your user is rejected when they use the url (for example because there are too many concurrent readers), the URL will trigger a HTTP error 403 "Forbidden", with the body containing a descriptive error message. You will probably want to handle these in a visually useful way for your users.
Downloads: For books and journal issues, downloads will be made to Adobe Digital Editions (or compatible Adobe DRM devices) with Adobe's "hard" DRM, or as an encrypted watermarked PDF ("soft" DRM) depending on the value of the drm parameter. If this is not supplied, then your account default preference will be used (this can be viewed under "Settings" in the Admin Tool). For more information, please see the FAQ.
If you supply the drm parameter with mode set to online, then the relevant DRM will be inherited for download requests from within the online ereader.
Get number of current readers for an item
/ReadGetCurrentReaders
Parameters
- book_id [optional*]
- a book ID (integer)
- journal_issue_id [optional*]
- a journal issue ID (integer)
- journal_article_id [optional*]
- a journal article ID (integer)
- chapter_id [optional*]
- a chapter ID (integer)
- customer_ref [mandatory] default: (empty)
- a customer identifier (string)
Returns
- count integer
- copies integer
Description
This method checks against the number of current readers for the specified item, for a specified customer. It returns the number of current readers and the number of copies available for reading in total (-1 if unlimited).
*One (and only one) item ID must be supplied, either book_id, journal_issue_id, journal_article_id or chapter_id.
The returned value count is the current number of readers (including both online and download readers), and copies is the number of copies available in all current subscriptions, but not including any available via a share group.
Typical use
This method could be used to ascertain whether an item can be read (i.e. not unavailable due to concurrent readers) before attempting to read, in order to avoid an error when invoking the URL returned by /Read.
Search
Searches are conducted either across the catalogue, searching either catalogue metadata or within the text of specific items. Searches can be saved against a customer identifier.
- /Search is for searching catalogue metadata, using keyword matching
- /SearchText is for searching within the text of one or more items, or your entire catalogue, using natural language matching
Natural language matching allows for the search term to be enclosed in double-quotes (") to prioritise a seach for the exact phrase.
Searches conducted via /Search can be saved, using /SearchSave, but fulltext searches via /SearchText cannot be saved.
Search catalogue
/Search
Parameters
- customer_ref optional
- a customer identifier (string)
- limit [optional] default / max: 500
- integer 1-500
- availability [optional] default: all
- all
- on_sale
- withdrawn
- subscribed
- open_access
- match_type [optional] default: any
- all
- any
- phrase
- title
- author
- item_type [optional] default: any
- any
- book
- journal
- language [optional] default: (empty)
- a language (3-character string, ISO 639-2/5 format)
- keywords [optional*] default: (empty)
- space-delimited keywords (i.e. search terms)
- collection_id [optional] default: (empty)
- a single CloudPublish collection ID
- thema [optional] default: (empty)
- a single Thema subject code
- imprints [optional*] default: (empty)
- comma-delimited imprints
- series [optional] default: (empty)
- a single series attribute (books only)
- series_volume [optional] default: (empty)
- a single series volume attribute (books only)
- series_code [optional] default: (empty)
- a single series code attribute (books only)
- date_published_from [optional] default: (empty)
- date in format YYYY-MM-DD
- date_published_to [optional] default: (empty)
- date in format YYYY-MM-DD
- open_access [optional] default: (empty = any)
- boolean 1/0
- sort_by [optional] default: score
- score
- item_id
- title
- date_published
- sort_order [optional] default: ascending for title and item_id, descending for date_published and score
- asc
- desc
*at least one of these parameters must be supplied
Returns
- data
- search_id integer
- results complex
- results:
- item_id integer
- item_type string
- title string
- subtitle string
- series string
- journal string
- journal_code string
- volume string
- issue string
- journal_id string
- journal_issue_id string
- parent_item_id integer
- parent_item_type string
- authors string (delimited by semicolon)
- edition string
- isbn string
- doi string
- thema_codes string
- thema_qualifiers string
- imprint string
- date_published date (YYYY-MM-DD)
- cover_thumbnail_url string (url)
- cover_midsize_url string (url)
- cover_fullsize_url string (url)
- open_access integer (1 or 0)
- available integer (1 or 0)
- withdrawn integer (1 or 0)
- subscribed integer (2 [partial access], 1 [full access], or 0 [no access])
Description
The search will run against common metadata fields for the specified items, restricted by item type, collection, subject (Thema), imprint, series, and/or publication date.
A maximum of 500 results is returned.
A customer_ref is required if availability is set to "subscribed". This has the effect of confining the search to the customer's own subscriptions.
If a customer_ref is supplied (regardless of the availability setting), the returned data includes a search ID which can be used to save a search for a customer (see /SearchSave below). This search ID is only valid for 24 hours: if the search is not saved, the ID is removed from the system after 24 hours.
If customer_ref is supplied, then the subscribed value in the returned data will be 0 if there is no subscription, or 1 if there is a matching subscription. If there is a matching subscription that provides partial access (e.g. a journal issue in the context of a journal search) then the returned value will be 2.
Save a search for a customer
/SearchSave
Parameters
- search_id [mandatory]
- a search ID (integer; returned from /Search)
- customer_ref [mandatory]
- a customer identifier (string)
- customer_user_ref [mandatory]
- a customer personalisation identifier (string)
- savename [optional] default: "Search #XXXXX" (where XXXXX is the search_id)
- unique [optional] default: 0
- 1 (yes) or 0 (no)
Returns
- data
- search_id integer
Description
This method allows a search (i.e., /Search) to be saved for a specified customer; the customer_ref must match the same customer_ref used for the original search.
The saved search must be associated with an individual user via the customer_user_ref parameter. This could be set to the same as customer_ref if the customer does not have multiple users.
Note that saving a search only applies to searches carried out with /Search, but not with /SearchText.
The savename does not need to be unique to the customer, although uniqueness (to the customer) can be enforced by passing unique=1. The savename can be modified by saving again, with a different value.
Search within the text of items
/SearchText
Parameters
- item_id [optional*]
- comma-delimited list of item IDs (string)
- item_type [mandatory]
- a single item type (book|chapter|journal_issue|journal_article)
- searchtext [mandatory]
- search phrase (string)
- customer_ref [optional]
- a customer identifier (string)
- return_distinct [optional]
- boolean (1 or 0, default: 0)
- language [optional] default: eng
- a language (3-character string, ISO 639-2/5 format)
*If not specified, the whole catalogue will be searched for the corresponding item_type, unless customer_ref is specified, in which case only that customer's subscriptions will be searched.
Returns
- data
- searchtext string
- num_results integer
- num_distinct_results integer
- results complex
- results:
- page integer
- text string
- item_type string
- item_id integer
- isbn string
- score float
Description
This method allows searching within the text of a specified item or items (of a single specified type). The function is quite different to /Search because this method only matches against a specific term or phrase, i.e. it is not possible to supply a list of keywords.
Note that if item_id is not specified, the whole catalogue will be searched, unless customer_ref is specified, in which case only that customer's subscriptions will be searched.
Important: If item_id is specified, and customer_ref is specified, only the subset of the items specified to which the customer is subscribed will be searched.
If return_distinct parameter is set to 1, then only the first result from each matched item is returned.
The language parameter should be the user's input language.
Retrieve a customer's saved searches
/SearchGetSavedSearches
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- customer_user_ref [optional]
- a customer personalisation identifier (string)
Returns
- data
- search_id integer
- savename integer
- customer_user_ref integer
- date_created integer
Description
This method allows retrieves all of a customer's saved searches. If customer_user_ref is supplied, then only that personalised user's searches will be returned, otherwise all of the customer's searches will be returned.
Run a saved search
/SearchRunSavedSearch
Parameters
- search_id [mandatory]
- a saved search ID (integer)
- customer_ref [mandatory]
- a customer identifier (integer)
Returns
- data
- search_id integer
- results complex
- results:
- (as for /Search)
Description
This method re-runs the search entirely with the same parameters as the original search. It can therefore return different results if the underlying catalogue has been updated.
Note that both the identifiers are mandatory.
Orders
An order is a submitted cart. When processed, it generates subscriptions and transactions.
Create an order
/OrderCreate
Parameters
- customer_ref [optional*]
- a customer identifier (string)
- customer_id [optional*]
- a customer id (integer)
- customer_user_ref [optional**]
- a customer user identifier (string)
- customer_user_id [optional**]
- a customer user id (integer)
- reference [optional]
- a reference number/code (string)
- status [optional]
- an order status (string)
- description [optional]
- an order description (string)
- book_items [optional]
- comma-delimited list of book IDs (string)
- book_items_quantity [optional, default 1]
- default quantity for each book item (integer)
- chapter_items [optional]
- comma-delimited list of chapter IDs (string)
- chapter_items_quantity [optional, default 1]
- default quantity for each chapter item (integer)
- journal_items [optional]
- comma-delimited list of journal IDs (string)
- journal_items_quantity [optional, default 1]
- default quantity for each journal item (integer)
- journal_issue_items [optional]
- comma-delimited list of journal issue IDs (string)
- journal_issue_items_quantity [optional, default 1]
- default quantity for each journal issue item (integer)
- journal_article_items [optional]
- comma-delimited list of journal article IDs (string)
- journal_article_items_quantity [optional, default 1]
- default quantity for each journal article item (integer)
- collection_id [optional]
- a collection ID
- collection_items_quantity [optional, default 1]
- default quantity for each collection item (integer)
- allow_online [optional, default per publisher settings]
- value for resulting subscription (boolean)
- allow_download [optional, default per publisher settings]
- value for resulting subscription (boolean)
- allow_printing [optional, default per publisher settings] (boolean)
- value for resulting subscription
- allow_unlimited_printing [optional, default per publisher settings] (boolean)
- value for resulting subscription
- print_percentage_allowance [optional, default per publisher settings]
- value for resulting subscription (integer, must be 0-100)
*/**at least one in each pair of these parameters must be supplied
Returns
- data
- order_id integer
Description
This method creates a new (empty) order. Items can be added here or one-by-one using /OrderUpdateItem. If adding items here, the default quantity (for each) is 1 if not specified.
Important note: CloudPublish does not store any pricing information within orders, because it expects you to do this within your own ecommerce platform. Orders exist within CloudPublish in order to provide a subscription mechanism only.
Returns an order_id for use with the related order-management methods.
Get order(s)
/OrderGet
Parameters
- order_id [optional]
- an order ID (integer)
- customer_ref [optional]
- a customer identifier (string)
- status [optional]
- an order status (string)
Returns
- data
- order_id integer
- customer_ref string
- status string
- reference string
- description string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- processed boolean (1/0)
- date_processed datetime (YYYY-MM-DD HH:MM:SS)
- transaction_id integer
- items complex
- items:
- item_id integer
- item_type string
- quantity -1, 0, or positive integer
- allow_online 1 or 0
- allow_download 1 or 0
Description
This method returns details about one or more matching orders. If no parameters are passed, all orders will be returned. The fields date_processed and transaction_id are only populated if processed is 1.
Update an order
/OrderUpdate
Parameters
- order_id [mandatory]
- the order ID (integer)
- reference [optional]
- a reference number/code (string)
- status [optional]
- an order status (string)
- description [optional]
- an order description (string)
Description
This method updates an order's fields. Only the values passed will be updated, but the complete order details (not including items) are returned.
Delete an order
/OrderDelete
Parameters
- order_id [mandatory]
- the order ID (integer)
- customer_ref [mandatory]
- a customer identifier (integer)
Description
This method deletes an order, and is applicable only to unprocessed orders.
Update an order's items
/OrderUpdateItem
Parameters
- order_id [mandatory]
- the order ID (integer)
- book_id [optional*]
- book ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
- quantity [mandatory]
- -1, 0, or positive integer
- allow_online [optional]
- boolean (1 or 0, default per publisher settings)
- allow_download [optional]
- boolean (1 or 0, default per publisher settings)
- allow_printing [optional]
- boolean (1 or 0, default per publisher settings)
- allow_unlimited_printing [optional]
- boolean (1 or 0, default per publisher settings)
- print_percentage_allowance [optional]
- integer (0-100, default per publisher settings)
- duration [optional] default: 0 (unlimited)
- integer
*one (and only one) of these parameters must be supplied
Returns
- data
- order_id integer
- item_id integer
- item_type string
- quantity integer
- allow_online 1 or 0
- allow_download 1 or 0
- duration integer
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates an order to set the number of a given item (either updating the quantity for an existing item or adding a new item). It is applicable only to unprocessed orders (i.e. not already converted to a transaction via /OrderProcess).
The quantity of an item typically corresponds to the number of copies of an ebook that will be available in the subscription that is created when the order is processed.
The quantity can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV), or a positive integer (which will correspond to the readers property of the resulting subscription).
The two allow_ parameters control whether the resulting subscription allows the book to be viewed online and/or downloaded.
The optional duration is the duration of the resulting subscription in seconds (rounded to the nearest day). A duration of 0 corresponds to an unlimited subscription; this is the default.
Delete an item from an order
/OrderDeleteItem
Parameters
- order_id [mandatory]
- the order ID (integer)
- book_id [optional*]
- book ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Description
This method updates an order to remove the specified item completely. It is applicable only to unprocessed orders (i.e. not already converted to a transaction via /OrderProcess).
Process an order (convert to subscriptions)
/OrderProcess
Parameters
- order_id [mandatory]
- the order ID (integer)
- customer_ref [mandatory]
- a customer identifier (string)
- customer_type [optional] default: inst
- a customer type (string: inst|ind)
- status [optional]
- a transaction status (string)
- invoice_number [optional]
- an invoice number or other reference code (uniqueness not enforced) (string)
- invoice_reference [optional]
- an additional invoice-related reference field (uniqueness not enforced) (string)
- invoice_date [optional]
- a date for the invoice (date in format YYYY-MM-DD)
- ecommerce_tx_ref [optional]
- an ecommerce transaction reference (uniqueness not enforced) (string)
- ecommerce_tx_status [optional]
- an ecommerce transaction status (string)
- start_date [optional] default: (current date)
- date in format YYYY-MM-DD
- end_date [optional] default: (empty)
- date in format YYYY-MM-DD
- notes [optional]
- notes to be attached to the transaction (text blob)
Returns
- data
- transaction_id integer
- customer_ref string
- status string
- invoice_number string
- invoice_reference string
- invoice_date date (YYYY-MM-DD)
- ecommerce_tx_ref string
- ecommerce_tx_status string
- notes string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- items complex
- subscriptions complex
- items:
- transaction_item_id integer
- item_id integer
- item_type string
- quantity -1, 0, or positive integer
- subscriptions:
- subscription_id integer
- item_id integer
- item_type string
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- allow_printing 1 or 0
- allow_unlimited_printing 1 or 0
- print_percentage_allowance integer 0-100
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
- date_created datetime (YYYY-MM-DD HH:MM:SS)
Description
This method creates subscriptions and a transaction from an order. The optional start_date sets the start-date of each subscription, and is by default the current date (at the time the order was processed). Each subscription's expiry date is either not set (i.e. unlimited) or is set according to the order item's duration which is added to the current date / start_date as applicable.
Pricing information for the transaction will be based on the customer_type parameter, which corresponds to the prices listed under price_inst and price_ind for the various item types (books, etc.).
Subscriptions
A subscription entitles a customer to access one or more copies of a book. It can be created directly or by processing an order. Note that creating a subscription directly also creates a corresponding transaction.
It is possible for a customer to have more than one subscription to a given book. In this case, the /CustomerSubscriptionCheck method will check all matching subscription, and will return affirmatively if at least one is valid/current for the book.
Create a subscription
/SubscriptionCreate
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- status [optional]
- a transaction status (string)
- invoice_number [optional]
- an invoice number or other reference code (uniqueness not enforced) (string)
- invoice_reference [optional]
- an additional invoice-related reference field (uniqueness not enforced) (string)
- invoice_date [optional]
- a date for the invoice (date in format YYYY-MM-DD)
- ecommerce_tx_ref [optional]
- an ecommerce transaction reference (uniqueness not enforced) (string)
- ecommerce_tx_status [optional]
- an ecommerce transaction status (string)
- notes [optional]
- notes to be attached to the transaction (text blob)
- book_id [optional*]
- book ID (integer, comma-delimited string of integers for multiple IDs)
- journal_id [optional*]
- journal ID (integer, comma-delimited string of integers for multiple IDs)
- journal_issue_id [optional*]
- journal issue ID (integer, comma-delimited string of integers for multiple IDs)
- journal_article_id [optional*]
- journal article ID (integer, comma-delimited string of integers for multiple IDs)
- collection_id [optional*]
- a collection ID (integer, comma-delimited string of integers for multiple IDs)
- access_model [optional] default: standard
- standard, pda, access_limit
- copies [optional] default: -1
- -1, 0, or positive integer
- allow_online [optional] default: 1
- 1 or 0 (integer)
- allow_download [optional] default: 1
- 1 or 0 (integer)
- allow_printing [optional] default: 1
- 1 or 0 (integer)
- allow_unlimited_printing [optional] default: 1
- 1 or 0 (integer)
- print_percentage_allowance [optional] default: 0
- 0-100 (integer / percentage)
- start_date [optional] default: (current date)
- date in format YYYY-MM-DD
- end_date [optional] default: 0000-00-00
- date in format YYYY-MM-DD
*one or more of these parameters must be supplied
Returns
- data
- transaction_id integer
- subscription_ids complex
- subscription_ids
- subscription_id** integer
**if multiple subscriptions are created as a result of passing in collection_id, then this element will appear multiple times
Description
This method creates a subscription (or, in the case of a collection, multiple subscripions) directly without transaction or order.
The copies of an item typically corresponds to the number of copies of an item that will be available in the subscription that is created when the order is processed.
The copies can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV, where the subscription will be updated later), or a positive integer (representing the maximum number of concurrent readers on this subscription).
Setting print_percentage_allowance to 0 means that the main account setting will be used instead. This is a rolling 30-day print allowance expressed as a percentage of the item's pagecount.
Setting allow_unlimited_printing requires allow_printing to be set to 1, and will cause print_percentage_allowance to be ignored.
This method returns a unique subscription_id and corresponding transaction_id for use in referring to this subscription later.
Note that if you subscribe to a Collection via collection_id, this creates subscriptions to the underlying books (or other items), and not to the Collection itself. Therefore, any subsequent changes to the Collection's contents will have no effect on customer subscriptions.
Get subscriptions data
/SubscriptionsGetAll
Parameters
- book_id [optional*] default: (empty)
- book ID (integer)
- journal_issue_id [optional*] default: (empty)
- a journal issue ID (integer)
- journal_article_id [optional*] default: (empty)
- a journal article ID (integer)
- chapter_id [optional*] default: (empty)
- a chapter ID (integer)
- order_id [optional] default: (empty)
- order ID (integer)
- start_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- start_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- end_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- end_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- allow_online [optional] default: (empty)
- boolean / integer (1 or 0) or empty to match both
- allow_download [optional] default: (empty)
- boolean / integer (1 or 0) or empty to match both
- access_model [optional] default: (empty)
- access model: standard, pda, access_limit or empty to match any
Returns
- data
- subscription_id integer
- item_id integer
- item_type string
- customer_ref string
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
*only one (or none) of these parameters may be supplied
Description
This method returns subscription data based on the parameters, or for all time if no parameters are supplied (up to a maximum of 500 records).
One (or none) of book_id, journal_issue_id, journal_article_id or chapter_id may be supplied. Specifying an item and/or order_id parameters allow subscriptions referring to a specific item and/or order to be returned.
To return subscriptions relating to a specific customer, use the /CustomerSubscriptionsGet method.
Get a subscription
/SubscriptionGet
Parameters
- subscription_id [mandatory]
- a subscription ID (integer)
Returns
- data
- subscription_id integer
- book_id integer
- customer_ref string
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns details about a subscription.
Update a subscription
/SubscriptionUpdate
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- subscription_id [mandatory]
- a subscription ID (integer)
- allow_online [optional] default: unchanged
- 1 or 0 (integer)
- allow_download [optional] default: unchanged
- 1 or 0 (integer)
- allow_printing [optional] default: 1
- 1 or 0 (integer)
- allow_unlimited_printing [optional] default: 1
- 1 or 0 (integer)
- print_percentage_allowance [optional] default: 0
- 0-100 (integer / percentage)
- copies [optional] default: unchanged
- -1, 0, or positive integer
- start_date [optional] default: unchanged
- date in format YYYY-MM-DD
- end_date [optional] default: unchanged
- date in format YYYY-MM-DD
Returns
- data
- subscription_id integer
- book_id integer
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates an existing subscription. Only the supplied parameters cause properties to be updated; all other properties of the subscription will be left unchanged.
Setting print_percentage_allowance to 0 means that the main account setting will be used instead. This is a rolling 30-day print allowance expressed as a percentage of the item's pagecount.
Setting allow_unlimited_printing requires allow_printing to be set to 1, and will cause print_percentage_allowance to be ignored.
Typical use
If you are implementing a PDA (patron-driven acquisition) or PPV (pay-per-view) model, you could set copies to 0 when initially creating the subscription, and then manually create an associated transaction (using /TransactionCreate) when you update the subscription based on customer action.
Delete a subscription
/SubscriptionDelete
Parameters
- subscription_id [mandatory]
- the order ID (integer)
- customer_ref [mandatory]
- a customer identifier (string)
Description
This method deletes a subscription.
Typical use
It is better to set the expiry of a subscription to a date in the past, rather than to delete a subscription, in order to preserve an audit trail.
Transactions
A Transaction is generated when an order is processed or when a subscription is created directly.
Get transactions data
/TransactionsGetAll
Parameters
- book_id [optional] default: (empty)
- book ID (integer)
- journal_id [optional] default: (empty)
- journal ID (integer)
- journal_issue_id [optional] default: (empty)
- journal issue ID (integer)
- journal_article_id [optional] default: (empty)
- journal article ID (integer)
- order_id [optional] default: (empty)
- order ID (integer)
- date_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- date_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- status [optional] default: (empty)
- string
Returns
- data
- transaction_id integer
- order_id integer
- customer_ref string
- invoice_number string
- invoice_reference string
- invoice_date date (YYYY-MM-DD)
- status string
- ecommerce_tx_ref string
- ecommerce_tx_status string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns transaction data based on the parameters, or for all time if no parameters are supplied (up to a maximum of 500 records).
The date_after and date_before parameters allow a date range to be specified; use just one to return all transactions before or after a date (i.e., invoice_date.
The book_id, journal_id, journal_issue_id, journal_article_id and order_id parameters allow transactions referring to a specific item or order to be returned.
To return transactions relating to a specific customer, use the /CustomerTransactionsGet method.
Get single transaction details
/TransactionGet
Parameters
- transaction_id [mandatory]
- the transaction ID (integer)
- customer_ref [mandatory]
- a customer identifier (string)
Returns
- data
- transaction_id integer
- order_id integer
- customer_ref string
- invoice_number string
- invoice_reference string
- invoice_date date (YYYY-MM-DD)
- status string
- ecommerce_tx_ref string
- ecommerce_tx_status string
- notes text
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- items complex
- items
- item_id integer
- item_type string
- item_title string
- item_identifier string
- price string
- price_currency string
- quantity integer
Description
This method returns full data for a single transaction, which must match the customer_ref.
Manually create a transaction
/TransactionCreate
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- invoice_number [optional]
- an invoice number (string)
- invoice_reference [optional]
- an invoice reference (string)
- invoice_date [optional]
- an invoice date in format YYYY-MM-DD
- status [optional]
- a transaction status (string)
- ecommerce_tx_ref [optional]
- an ecommerce transaction reference (string)
- ecommerce_tx_status [optional]
- an ecommerce transaction status (string)
- notes [optional]
- transaction notes (text blob)
Returns
- data
- transaction_id integer
Description
This method manually creates a transaction. In itself, it is an empty container for transaction items, which should then be created one by one using /TransactionItemUpdate
Typical use
Transactions created manually are useful for implementing PDA or PPV.
The status field can be empty or can be set to one of a set of values relevant to your own accounts/billing system, e.g. "invoiced", "paid", "cancelled", etc. You can then retrieve all matching transactions using the status parameter of /TransactionsGetAll.
Update a transaction
/TransactionUpdate
Parameters
- transaction_id [mandatory]
- the transaction ID (integer)
- invoice_number [optional]
- an invoice number (string)
- invoice_reference [optional]
- an invoice reference (string)
- invoice_date [optional]
- an invoice date in format YYYY-MM-DD
- status [optional]
- a transaction status (string)
- ecommerce_tx_ref [optional]
- an ecommerce transaction reference (string)
- ecommerce_tx_status [optional]
- an ecommerce transaction status (string)
- notes [optional]
- transaction notes (text blob)
Returns
- data
- transaction_id integer
- order_id integer
- customer_ref string
- invoice_number string
- invoice_reference string
- invoice_date date (YYYY-MM-DD)
- status string
- ecommerce_tx_ref string
- ecommerce_tx_status string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates a transaction by changing any of the above attributes. When adding notes, remember that the value will be replaced rather than appended.
Typical use
To update a transaction status (e.g. change a status from "PENDING" to "PAID")
Delete a transaction
/TransactionDelete
Parameters
- transaction_id [mandatory]
- the transaction ID (integer)
- customer_ref [mandatory]
- the customer idenfitier (string)
Description
Deletes a transaction and (NB) all associated transaction items and subscriptions.
Update a transaction's items
/TransactionUpdateItem
Parameters
- transaction_id [mandatory]
- the transaction ID (integer)
- book_id [optional*]
- book ID (integer)
- chapter_id [optional*]
- chapter ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
- quantity [mandatory]
- -1, 0, or positive integer
*one (and only one) of these parameters must be supplied
Returns
- data
- transaction_item_id integer
Description
This method updates a transaction to set the number of a given item (either updating the quantity for an existing item or adding a new item). Note that by altering the transaction's items, the transaction will become inconsistent with any original order that created the transaction.
The quantity of an item typically corresponds to the number of copies of an item that will be available in the subscription. NB, any associated subscriptions are NOT updated: this must be done by /SubscriptionUpdate.
The quantity can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV), or a positive integer.
Delete an item from a transaction
/TransactionDeleteItem
Parameters
- transaction_id [mandatory]
- the transaction ID (integer)
- book_id [optional*]
- book ID (integer)
- chapter_id [optional*]
- chapter ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Description
This method updates an order to remove the specified item completely. NB, any associated subscriptions are NOT updated: this must be done by /SubscriptionUpdate.
Access Tokens
An access token provides access to content for a user (possibly but not necessarily an existing customer), usually with various restrictions in place.
Create an access token
/AccessTokenCreate
Parameters
- quantity [optional] default: 1
- quantity to generate, min 1, max 100 (integer)
- active [optional] default: 0
- whether the access token is active (boolean 1/0)
- customer_ref [optional] default: (empty)
- a customer identifier (string)
- item_type [optional] default: (empty)
- a single item type (book|chapter|journal_issue|journal_article|collection)
- item_id [optional] default: (empty)
- an item identifier (integer)
- item_restriction [optional] default: (empty)
- e.g. volume=53|volume=54 (string)
- max_uses [optional] default: -1
- -1, or positive integer
- allow_online [optional] default: 1
- 1 or 0 (integer)
- allow_download [optional] default: 1
- 1 or 0 (integer)
- allow_printing [optional] default: 1
- 1 or 0 (integer)
- allow_unlimited_printing [optional] default: 1
- 1 or 0 (integer)
- print_percentage_allowance [optional] default: 0
- 0-100 (integer / percentage)
- start_date [optional] default: (current date)
- date in format YYYY-MM-DD
- end_date [optional] default: 0000-00-00
- date in format YYYY-MM-DD
*one or more of these parameters must be supplied
Returns
- data
- access_tokens** complex
- access_tokens
- access_token_id integer
- code string
**if multiple access tokens are created as a result of passing in a quantity greater than 1, then this element will appear multiple times
Description
This method creates one or more access tokens with the specified restrictions (if any). These can be redeemed via the /Read API method, or via an integration-specific method.
Customers
A customer is a single actor within your customer-base. In CloudPublish, customers are described by a unique identifier, customer_ref (string), which we recommend setting to be the same as the complete corresponding customer record in your own systems.
A CloudPublish customer is typically an institution / organisation entity, and will have one or more customer users, which can be created and managed by further API calls as described below. Again, these can correspond to users in your own systems, this time via the unique identifier customer_user_ref.
Identify a customer
/CustomerIdentify
Parameters
- ip_address [mandatory]
- an IP address (string)
- referrer_url [mandatory]
- a URL (string)
- shibboleth_entity_id [optional]
- a Shibboleth Entity ID (string)
- openathens_id [optional]
- an OpenAthens organisation ID (string)
- customer_ref [optional]
- a CloudPublish customer identifier (string)
Returns
- data
- customer_id integer
- access_method string
Description
This method will identify a customer (if the customer is already created via the Admin Tool). Both ip_address and referrer_url are required; they are tested in that order, followed by shibboleth_entity_id, openathens_id, and customer_ref.
Retrieve customer details
/CustomerGet
Parameters
- customer_id* [optional]
- a customer id (integer)
- customer_ref* [optional]
- a customer identifier (string)
*one (and only one) of these parameters must be supplied
Returns
- data
- ref string
- organisation string
- address string
- postcode string
- phone string
- country string
- contact_name string
- contact_email string
- logo string
- shibboleth_entity_id string
- shibboleth_entitlement string
- shibboleth_affiliations string
- shibboleth_admin_affiliations string
- openathens_org_ids string
- ip_range string
- referrer_url string
- share_group string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method will return details for a single customer, based on the supplied identifier.
Get customer-specific order information
/CustomerOrdersGet
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- date_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- date_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
Returns
- data
- order_id integer
- customer_ref string
- status string
- reference string
- description string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- processed boolean (1/0)
- date_processed datetime (YYYY-MM-DD HH:MM:SS)
- transaction_id integer
- items complex
- items:
- item_id integer
- item_type string
- quantity -1, 0, or positive integer
- allow_online 1 or 0
- allow_download 1 or 0
Description
This method returns all order information for a specified customer (within / after / before certain creation dates if specified). The fields date_processed and transaction_id are only populated if processed is 1.
Get customer-specific subscription information
/CustomerSubscriptionsGet
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- current_only [optional] default: 1
- boolean (1 or 0)
- item_type [optional] default: (empty)
- string (book|journal)
- book_id [optional] default: (empty)
- book ID (integer)
- chapter_id [optional] default: (empty)
- chapter ID (integer)
- journal_id [optional] default: (empty)
- journal ID (integer)
- journal_issue_id [optional] default: (empty)
- journal issue ID (integer)
- journal_article_id [optional] default: (empty)
- journal article ID (integer)
- start_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- start_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- end_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- end_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- allow_online [optional] default: (empty)
- boolean / integer (1 or 0) or empty to match both
- allow_download [optional] default: (empty)
- boolean / integer (1 or 0) or empty to match both
- include_share_group [optional] default: 0
- boolean / integer (1 or 0)
Returns
- data
- subscription_id integer
- item_id integer
- item_type string
- customer_ref string
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
- is_valid 1 or 0
- via_share_group 1 or 0
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns subscription information for a specified customer (within / after / before certain subscription start/end dates if specified), including current valid subscriptions only if current_only is 1.
If item_type is book, then all subscribed books will be returned (including the books for which chapters are subscribed). Similarly if item_type is journal, then all subscribed journals (even if only a single article / volume / issue is subscribed) will be returned.
Alternatively, if one of book_id, journal_id, journal_issue_id or journal_article_id is passed, then only subscriptions corresponding to the specified item are returned (usually but not always this will be just one subscription).
The is_valid parameter in the returned data indicates whether the subscription is current / valid.
The include_share_group parameter will include subscriptions available to this customer via their share_group - by default these are not included.
Check whether a customer has a subscription to an item
/CustomerSubscriptionCheck
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- book_id [optional*]
- book ID (integer)
- chapter_id [optional*]
- chapter ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Returns
- data
- result boolean (1/0)
- subscription_id integer
- copies integer
- allow_online 1 or 0
- allow_download 1 or 0
- start_date date (YYYY-MM-DD)
- end_date date (YYYY-MM-DD)
Description
This method returns 1 or 0 (i.e. whether or not a valid subscription exists), plus the subscription_id, expiry date and number of copies (if there is a valid subscription), for the specified item. Note that this method checks only the customer's direct subscriptions, not those of any other customer linked via share_group. To include those, use /CustomerAccessCheck instead.
Check whether a customer can access an item
/CustomerAccessCheck
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- book_id [optional*]
- book ID (integer)
- chapter_id [optional*]
- chapter ID (integer)
- journal_id [optional*]
- journal ID (integer)
- journal_issue_id [optional*]
- journal issue ID (integer)
- journal_article_id [optional*]
- journal article ID (integer)
- access_now [optional] default: 0
- boolean (1 or 0)
- access_type [optional] default: any
- any / online / download
*one (and only one) of these parameters must be supplied
Returns
- data
- result boolean (1/0)
Description
This method checks the customer's own subscriptions and those accessible via share_group. It simply returns 1 or 0 (i.e. whether or not a valid subscription exists) for the specified item.
Get customer-specific transaction information
/CustomerTransactionsGet
Parameters
- customer_ref [mandatory]
- a customer identifier (string)
- book_id [optional] default: (empty)
- book ID (integer)
- chapter_id [optional] default: (empty)
- chapter ID (integer)
- journal_id [optional] default: (empty)
- journal ID (integer)
- journal_issue_id [optional] default: (empty)
- journal issue ID (integer)
- journal_article_id [optional] default: (empty)
- journal article ID (integer)
- order_id [optional] default: (empty)
- order ID (integer)
- date_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- date_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- status [optional] default: (empty)
- string
Returns
- data
- transaction_id integer
- order_id integer
- customer_ref string
- invoice_number string
- invoice_reference string
- invoice_date date (YYYY-MM-DD)
- status string
- ecommerce_tx_ref string
- ecommerce_tx_status string
- notes text
- date_created datetime (YYYY-MM-DD HH:MM:SS)
- last_modified datetime (YYYY-MM-DD HH:MM:SS)
- items complex
- items
- item_id integer
- item_type string
- quantity integer
Description
This method returns a list of the transactions associated with the specified customer (within / after / before certain invoice dates if specified).
Get customer usage statistics (excl. COUNTER stats)
/CustomerStatistics
Parameters
- format [optional] default: json
- json
- csv
- customer_ref [optional]
- a customer identifier (string)
- customer_user_ref [optional]
- a customer user identifier (string)
- event_type [optional]
- an event type (string: read|read_online|read_download|catalogue_search|item_turnaway)
- item_type [optional]
- an item type (string: book|journal)
- book_id [optional] default: (empty)
- book ID (integer)
- chapter_id [optional] default: (empty)
- chapter ID (integer)
- journal_id [optional] default: (empty)
- journal ID (integer)
- journal_issue_id [optional] default: (empty)
- journal issue ID (integer)
- journal_article_id [optional] default: (empty)
- journal article ID (integer)
- date_after [optional] default: 0000-00-00
- date in format YYYY-MM-DD
- date_before [optional] default: 0000-00-00
- date in format YYYY-MM-DD
Returns
- data
- customer_ref string
- item_type string
- item_id integer
- item_title string
- item_identifier string
- item_doi string
- event string
- event_data_1 string
- event_data_2 string
- date_created datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns statistics about customer item access and other customer-related events within CloudPublish. event shows the type of event; event_data_1 and event_data_2 show extra data as applicable (e.g. search terms). If customer_ref is passed, data will be restricted to that customer only. If book_id, journal_id, journal_issue_id or journal_article_id is passed, data will be restricted to that item (or those items) only. Both can be passed for a precise subset of the available data.
If customer_user_ref is passed, then customer_ref is also required. The customer_user_ref allows the statistics for related organisations to be included. If customer_user_ref represents a CustomerUser with admin=1 then all Customers matching that CustomerUser's admin_stats_for will be included in the output.
Get statistical reports in COUNTER format.
/CustomerCOUNTERData
Parameters
- report [mandatory]
- book_report_1
- book_report_3
- book_report_5
- journal_report_1
- journal_report_2
- journal_report_5
- customer_ref [mandatory]
- customer identifier, comma-delimited for multiple customers (string)
- customer_user_ref [optional]
- a customer user identifier (string)
- date_after [mandatory]
- partial date in format YYYY-MM
- date_before [mandatory]
- partial date in format YYYY-MM
Returns
- data
- (structure depends on report selected)
Description
This method returns statistics about customer ebook access in COUNTER format. The reports available are as follows:
- book_report_1 - Number of successful title requests by month and title
- book_report_3 - Turnaways by month and title
- book_report_5 - Total searches and sessions by month and title
The report runs from the start of the month specified in date_after to the end of the month specified in date_before.
Passing customer_user_ref allows the admin_stats_for attribute of an end-user to be taken into account (i.e. to return data for the linked accounts).
Create a Customer User
/CustomerUserCreate
Parameters
- customer_ref [mandatory]
- customer identifier (string)
- username [mandatory]
- customer user identifier (unique, string)
- password [mandatory]
- customer password (string)
- name [optional] default: (empty)
- customer user's real name (string)
- admin [optional] default: 0
- allows admin-level access (boolean 1/0)
- admin_users_for [optional] default: (empty)
- Other Customer IDs that this user can access for user admin (string, comma-delimited ints)
- admin_subs_for [optional] default: (empty)
- Other Customer IDs that this user can access for subscription admin (string, comma-delimited ints)
- admin_stats_for [optional] default: (empty)
- Other Customer IDs that this user can access for statistics admin (string, comma-delimited ints)
- expiry [optional] default: 0000-00-00 (no expiry)
- account expiry date (date, YYYY-MM-DD)
Returns
- data
- customer_id integer
- customer_ref string
- customer_user_id integer
- name string
- username string
- password string
- expiry date
- has_expired boolean
- admin boolean
- admin_users_for string
- admin_subs_for string
- admin_stats_for string
Description
This method creates an end-user for a customer. These details can also be changed on the Admin Site, therefore it is important to resync your local records (e.g. of the user's passwords) regularly by using /CustomerUserGet.
The various admin attributes are for your use and do not confer any privileges within CloudPublish, and the expiry attribute has no effect except to provide you with a convenient mechanism via the has_expired value.
It is also possible to create and manage these users manually via the Admin Site.
Retrieve a Customer User
/CustomerUserGet
Parameters
- customer_id [optional*]
- customer identifier (int)
- customer_ref [optional*]
- customer identifier (string)
- customer_user_id [optional**]
- customer user identifier (integer)
- username [optional**]
- customer user identifier (string)
*/** one of each of these pairs of values must be supplied
Returns
- data
- customer_id integer
- customer_ref string
- customer_user_id integer
- customer_organisation string
- customer_logo string
- customer_address string
- customer_postcode string
- customer_phone string
- customer_country string
- customer_vat_number string
- name string
- username string
- password string
- expiry date
- has_expired boolean
- admin boolean
- admin_users_for string
- admin_subs_for string
- admin_stats_for string
- cart complex; currently a placeholder only
Description
This method retrieves a customer end-user for a customer that was previously created with /CustomerUserCreate or via the Admin Site. Several values from the associated Customer model are also returned, for convenience.
Retrieve all Customer Users
/CustomerUserGetAll
Parameters
- customer_id [optional*]
- customer identifier (int)
- customer_ref [optional*]
- customer identifier (string)
* one of these must be supplied
Returns
- data
- customer_id integer
- customer_ref string
- customer_user_id integer
- customer_organisation string
- customer_logo string
- name string
- username string
- password string
- expiry date
- has_expired boolean
- admin boolean
- admin_users_for string
- admin_subs_for string
- admin_stats_for string
Description
This method retrieves all of a customer's end-users that were previously created with /CustomerUserCreate or via the Admin Site. Several values from the associated Customer model are also returned, for convenience.
Update a Customer User
/CustomerUserUpdate
Parameters
- customer_id [optional*]
- customer identifier (int)
- customer_ref [optional*]
- customer identifier (string)
- customer_user_id [optional**]
- customer user identifier (integer)
- username [optional**]
- customer user identifier (string)
- password [mandatory]
- customer password (string)
- name [optional] default: (empty)
- customer user's real name (string)
- admin [optional] default: 0
- allows admin-level access (boolean 1/0)
- admin_users_for [optional] default: (empty)
- Other Customer IDs that this user can access for user admin (string, comma-delimited ints)
- admin_subs_for [optional] default: (empty)
- Other Customer IDs that this user can access for subscription admin (string, comma-delimited ints)
- admin_stats_for [optional] default: (empty)
- Other Customer IDs that this user can access for statistics admin (string, comma-delimited ints)
- expiry [optional] default: 0000-00-00 (no expiry)
- account expiry date (date, YYYY-MM-DD)
- customer_organisation [optional] default: (empty)
- +customer organisation (string)
- customer_logo [optional] default: (empty)
- +customer logo (string)
- customer_address [optional] default: (empty)
- +customer address (string)
- customer_postcode [optional] default: (empty)
- +customer postcode (string)
- customer_phone [optional] default: (empty)
- +customer phone (string)
- customer_country [optional] default: (empty)
- +customer country (string)
- customer_vat_number [optional] default: (empty)
- +customer VAT number (string)