POST v3/catalog - All

In almost all use cases this API has been replaced by the v4/products API. This endpoint is primarily for legacy customers. New integrations should use v4/products as their canonical source of catalog information.

The v3/catalog API will retrieve a company's entire catalog. Companies can choose specific requests to filter results and also configure paging on how many records are returned per page. Basic delta abilities are also available via this API, using the <updated> element to only return products that have changed since the last time a client pulled the catalog. It does require that the client keep track of the last pull date to ensure the right date is entered and product changes are not missed. Other notes:

Verb/URI

POST https://api.vitalsource.com/v3/catalog

Data Definitions

Name
Usage
Description
Data Type
Example
Required
  URL param Pulls everything that is assigned to the calling company both distribution set(s) and manual rights N/A

v3/catalog

Yes 
sets URL param Pulls products which are part of a companies assigned distribution sets (national, custom, etc.) string 

v3/sets

No
manual URL param Pulls only products that have been manually assigned to requesting company string

v3/manual

No 
page Message body Page number for the catalog request; default pagination is 100 per page. Depending on the number of records in your distribution set, you will call multiple pages of data. Paging starts at Page 0. integer

123

No
per-page Message body Valid values between 100 and 1,000; recommendation is to pull 1,000 at a time. integer

150

No
created Message body

Available operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101).

Accepts any valid ISO-8601 formatted date. Specify to return items based on a specific timestamp. Including only a date will default the timestamp to be midnight UTC.

ISO-8601

ge 2010-07-01

No
updated Message body 

Available operators are gt (>), ge (>=), lt (<), le (<=). The default value for this is "inception" (gt 20000101).

Accepts any valid ISO-8601 formatted date. Specify to return items based on a specific timestamp. Including only a date will default the timestamp to be midnight UTC.

ISO-8601 

ge 2010-07-31

No 
include-packages Message body

Adds package details to response body

string

true

No
condition Message body

Used if you are searching for a specific product, this allows for a search via SKU, or ISBN. Only provide when looking for a specific title.

SKU

<condition type="identifier">

VBID_OR_SKU</condition>

 

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS

Request Body - default example

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
	<page>0</page>

	<per-page>1000</per-page>
	<created>ge 2000-01-01</created>
	<updated>ge 2000-01-01</updated>

	<include-packages>true</include-packages>
</catalog>

Request Body - identifier example

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
	<page>0</page>

	<per-page>1000</per-page>
	<created>ge 2018-01-01</created>
	<updated>ge 2018-01-01</updated>

	<condition type="identifier">VBID_OR_SKU</condition>
	<include-packages>true</include-packages>
</catalog>

Response

Response body - default (incomplete)

<catalog items="17002" total-pages="171" page="0" per-page="100">
  <?xml version="1.0" encoding="UTF-8"?>
<catalog items="3" total-pages="1" page="0" per-page="1000" status="complete">
<item>
<sku>BOOKSHELF-TUTORIAL</sku>
<vbid>BOOKSHELF-TUTORIAL</vbid>
<created>Mon, 04 Aug 2014 13:37:55 +0000</created>
<updated>Fri, 19 Oct 2018 20:56:37 +0000</updated>
<off-sale-date/>
<type>Single</type>
<downloadable-duration>perpetual</downloadable-duration>
<online-duration>365 days</online-duration>
<book-format>ePub</book-format>
<build-status>In Inventory</build-status>
<url>https://www.vitalsource.com/textbooks?term=BOOKSHELFTUTORIAL</url>
<description/>
<publication-date/>
<author>VSM</author>
<title>Bookshelf Tutorial</title>
<sort-title>Bookshelf Tutorial</sort-title>
<edition>0</edition>
<icon-url>https://covers.vitalbook.com/vbid/BOOKSHELF-TUTORIAL/width/120</icon-url>
<sampleable>true</sampleable>
<page-count>0</page-count>
<copyright-date/>
<copyright-year/>
........
........
<aliases>
<eisbn-canonical/>
<isbn-canonical>BOOKSHELFTUTORIAL</isbn-canonical>
<print-isbn-canonical/>
<fpid/>
<isbn13/>
<isbn10/>
<additional-isbns>
<isbn type="e-isbn-10">0123456789</isbn>
</additional-isbns>
</aliases>
.......
.......
<pricelist>
<publisher-list-price>0.00</publisher-list-price>
<agency-price/>
<digital-list-price>0.00</digital-list-price>
<sell-price/>
</pricelist>
<publisher>
<publisher-name>VitalSource Technologies</publisher-name>
<imprint-name>VCS Internal &amp; Sales</imprint-name>
</publisher>
.......
.......
</catalog> 

Response Descriptions

Name
Description
items Returns the count of total items based on the request made
total-pages Total number of pages available; when building an entire catalog, you will need to use this number to call the proper amount of pages to ingest your entire catalog
page Current page
per-page Records being returned per page based on your initial request
item Main element; will return multiple <item /> elements when retrieving an entire list, one for each item returned
sku Unique product SKU; this will be used to make additional calls to create codes
created Date the product was created
updated Date the product was last updated
off-sale-date Date the product will be removed from distribution
type Rental, Single, Package, or Demo will be returned
downloadable-duration Duration of license options for the downloadable version of the book, all values are returned in days
online-duration Duration of license options for the online version of book, all values are returned in days
book-format Format of the book; dashML, pbk, pdf, ePub are valid returns. If book is available in multiple formats, it will return multiple elements for each as each has a unique SKU
kind The type of the asset/product including book, chapter, eresource, title
discount code The discount code returned from publishers, typically from an ONIX feed. Alpha numeric value
url Store URL for book
description Author/publisher description of book, returned as plain text
publication-date MM/YYYY of publication date
author Author(s) name
title Asset title
sort-title  
edition Asset edition
icon-url URL to thumbnail icon
sampleable Boolean value to identify whether the book is available for faculty sampling
page-count Number of pages in the book
copyright-date Full copyright date
copyright-year Copyright year
print-drm-text Display text for printing rules
copy-drm-text Display text for copying rules
subjects Element will return two sets of subject schemas, if available (bisac and coursemart)
parent-isbn For content types of chapters this will be populated tp group chapters back to titles
subject schema=biscac Returns both the BISAC code and the display text for the subject
pricelist Element that displays the pricing details for the specific SKU/product
publisher-list-price  
agency-price  
digital-list-price  
sell-price  
publisher Publisher details
publisher-name Publisher name 
imprint-name Imprint name
distributable Returns a true or false; this is used to determine if an item returned is available for sale within the caller's catalog. A false return means it has either been removed from distribution or there were problems with the build. If you are using deltas and wish to track what has been removed from your catalog, this element will change to false as items are removed from your distribution set. You cannot sell assets marked false.
aliases Element that returns the other ISBNs and identifiers related to the specific SKU/product
eisbn-canonical eISBN of the product
isbn-canonical ISBN of the product
print-isbn-canonical PrintISBN of product
additional-isbns An array of <isbn> elements that will return. These are ISBNs that relate to the product <item>. There can be 0 to many of these returned per product and should be used as a way to discover additional content.
fpid CourseSmartID of product returned if it exists (this can be empty)
vpid-equivalent  VitalSource specific equivalent where an older title was retired and now linked to a new title
isbn13 ISBN13 of product returned; will contain dashes
isbn10 ISBN10 of product returned; will contain dashes
owner Element that returns the owner of the product returned
company Element that displays the company information; if more than one company (child companies) owns the product, it will return each in separate company elements
id VitalSource Manage company ID
name VitalSource Manage company name
distributor VitalSource Manage distributors of this asset
build-status
Status of the asset in VitalSource Manage


Error Codes

HTTP & Error messages 
Message
Notes
200

 

Success. Errors provided simultaneously
422

Bad parameters

 
422

Bad page number

 
422

Bad per-page number

 
422

Bad date parameter

 
992

API user company is misconfigured (has multiple companies)

 

 

Was this article helpful?
1 out of 2 found this helpful

Comments

0 comments

Article is closed for comments.