GET v4/products/:vbid - Title, TOC, Metadata

The Products API is used to retrieve information about an individual title in your catalog. It includes the same data you would see in in v4/products, as well as information on eBook accessibility that is not available in the general catalog.We also offer /TOC ?include_details and  ?type requests.



Data Definitions

Data Type
vbid URL param The VitalBookID (VBID) for the title string


toc URL param Asset table of contents request string


include_details URL param  Valid groups: metadata,subjects, identifiers,accessibility,store  string


type URL param Specifiers: Packages,Rental,Single string




Request Headers

Accept: application/json

Request Header - vbid example

This request would return only the specified asset in payload


Request Header - toc example

This request would return the XML table of contents for the asset in payload


Request Header - include_details - accessibility example

This request will add the accessibility array to the asset payload


Request Header - type -  example

This request will add variants to the asset payload




Response Body - vbid example

"vbid": "L-999-70031",
"kind": "great book",
"identifiers": {
"print_isbn_canonical": "null",
"eisbn_canonical": null
"title": "Fantastic Fables",
"format": "ePub",
"publisher": "Hayes Barton Press",
"edition": 0,
"contributors": [
"name": "Ambrose Bierce",
"type": null
"language": null,
"created": "2006-03-04T06:20:36Z",
"off_sale_date": null,
"print_restrictions": -1,
"copy_restrictions": -1,
"resource_links": {
"metadata": "",
"cover_image": "",
"table_of_contents": "",
"store_url": ""
"related_products": {
"previous_edition": null,
"new_edition": null,
"ancillary": null
"sales_rights": [],
"exclude_sales_rights": [],
"variants": [
"duration": "perpetual",
"online_duration": "365",
"sku": "L-999-70030",
"type": "Single",
"distributable": true,
"prices": [
"type": "digital-list-price",
"value": "5.00",
"currency": "USD",
"discount_code": null,
"territory": null
"updated": "2019-01-01T17:17:35Z",
"contents": []

Response Body - toc example (partial)

"table_of_contents": [
"title": "181 ORIGINAL FABLES",
"path": "/OPS/loc_001.xhtml",
"level": 1,
"cfi": "/6/4[idloc_001.xhtml-itemref]",
"kind": "document_container",
"page": "",
"data": []
"title": "The Moral Principle and the Material Interest",
"path": "/OPS/loc_002.xhtml",
"level": 2,
"cfi": "/6/6[idloc_002.xhtml-itemref]",
"kind": "document",
"page": "",
"data": []
"title": "The Crimson Candle",
"path": "/OPS/loc_003.xhtml",
"level": 2,
"cfi": "/6/8[idloc_003.xhtml-itemref]",
"kind": "document",
"page": "",
"data": []

Response Body - accessibility example

"vbid": "9781464182242",
"kind": "book",
"identifiers": {
"print_isbn_canonical": "9781464182235",
"eisbn_canonical": "9781464182242"
"title": "Psychology of Sex and Gender",
"format": "ePub",
"publisher": "Macmillan Higher Education",
"edition": 0,
"contributors": [
"name": "Susan Burns",
"type": null
"language": "English",
"created": "2018-12-03T20:49:05Z",
"off_sale_date": null,
"print_restrictions": 10,
"copy_restrictions": 2,
"resource_links": {
"metadata": "",
"cover_image": "",
"table_of_contents": "",
"store_url": ""
Deleted section
"schema:accessibilityFeature": [
"displayTransformability/background color",
"schema:accessibilityHazard": [
"schema:accessibilityAPI": [
"schema:accessibilityControl": [
"schema:accessibilitySummary": {
"": "long description present using aria-describedby; Please enable reading of punctuation in your AT in order to hear necessary pedagogical information."
"a11y:certifiedBy": [
"a11y:certifierCredential": [

Response Descriptions - default

The standard response body, returned in your requested format.

vbid The VitalBookID (VBID) for the title
kind The type of asset/product including book, chapter, title, online resource, online resource bundle
print_isbn_canonical Print ISBN of asset returned
eisbn_canonical eISBN of asset returned
title Asset title
format Format of the book; dashML, pbk, pdf, ePub are valid returns.
publisher Name of the publisher
edition Edition of the book
contributors - name Names of the contributors for the asset
contributors - type Type of contributor
language Language of the asset
created Date the asset was created
off_sale_date Date the asset will be removed from distribution
print_restrictions Display text for printing rules
copy_restrictions Display text for copying rules
resource_links - metadata Additional API call to gather additional metadata about the asset
resource_links - cover_image URL for the cover image of the asset
resource_links - table_of_contents Additional API call to return the Table of Contents for the asset
resource_links - store_url VitalSource store URL for the asset
previous_edition Previous edition of the asset
next_edition Next edition of the asset 
sales rights array of country(s) where assets can be sold
exclude_sales_rights array of country(s) where assets cannot be sold
variants additional products based on the asset
variants - duration Duration for the downloadable version of the product variant, all values are returned as number of days or perpetual
variants - online_duration Duration for the online version of the product variant, all values are returned as number of days or perpetual
variants - sku Unique product SKU for the product variant; this will be used to make additional API calls to create codes
variants - type Type of product that is the variant
variants - distributable Value determines whether or not the items can be sold. Items will be in the product response with distributable = false due to deltas and identification of products that have been removed from sale. 
variants - prices - type Pricing details for the specific product variant
variants - prices - value Price of the product variant
variants - prices - currency Country code of the currency
variants - prices - discount_codes The discount code returned from publishers, typically from an ONIX feed

A channel-specific ISBN that points to one product [{JSON array}]

variants/channel_ids/[]/channel The (system) name of the channel
variants/channel_ids/[]/identifier The chosen identifier string.
variants - prices - territory  
variants - updated Date the product variant was last updated
variants/pos_tags List of Point of Sale tags assigned to this product variant
contents This will return the SKUs that are included in a package


Response Descriptions - include_details 

Include_details groups allow a user to request additional blocks of metadata. By default due to the amount of metadata provided for products the response will only include a smaller subset of data for ease of ingestion. If users would like additional book metadata, identifiers or subjects they can be requested using the include_details parameter below. You can request one to many of these response groups separated by a comma.

metadata Returns additional metadata for a title. Descriptions, publication dates and other relevant metadata listed in the data dictionary. 
identifiers Returns all of the alias identifiers VitalSource has related to a specific title. This can be used to help power your search index to allow lookup. These often will be the hardcover, spiral bound versions of ISBNs associated to the same digital title.
subjects Returns BIASC categories for use of grouping titles in a users commerce platform.
accessibility Returns the accessibility features for a title. Accessibility features are data like whether a title has audio captions or if images have descriptions for the visually impaired.


Response Descriptions - metadata

subtitle Subtitle of the asset
description Description of the asset
sort_title Sort title of the asset
copyright_date Date of copyright for the asset
publication_date Date of copyright for the asset
page_count Page count of the asset (if provided by the publisher)
imprint_name Name of the publisher imprint
parent_isbn If the asset is a child to a parent asset (ex. single chapter of a book) this value is the parent asset
publisher_list_price The publisher provided list price of the asset


Response Descriptions - subjects

schema Subject classification schema
code Subject code
name Subject name


Response Descriptions - identifiers

isbn_canonical Canonical ISBN of the asset
isbn_10 ISBN 10 of the asset
isbn_13 ISBN 13 of the asset
e_isbn eISBN of the asset
print_isbn Print ISBN of the asset
saleable_print_isbn_10 Saleable Print ISBN 10
saleable_print_isbn_13 Saleable Print ISBN 13
vbid_alias VBID alias
fpid_alias FPID alias
print_isbn_10 Print ISBN 10
print_isbn_13 Print ISBN 13
e_isbn_10 eISBN 10
e_isbn_13 eISBN 13
fpid_isbn_10 FPID ISBN 10
fpid_isbn_13 FPID ISBN 13
csm_sku CSM SKU
fpid10_alias FPID 10 alias
fpid13_alias FPID 13 alias
vbid10_alias VBID 10 alias
vbid13_alias VBID 13 alias
fpid FPID


Response Descriptions - store

block_search Block from store search


Response Descriptions - accessibility

The data that is returned in the accessibility_options array can be semantically understood by referencing the a11y w3c schemas here:


 How to utilize the TOC response

TOC's are built at ingestion by VitalSource based upon the XML submitted by the publisher of the content. Any update to the content by the publisher could change the TOC and break hard coded links. Best practice is to dynamically generate links, based upon the currently available version.

This is the example request

A TOC response will contain CFI structures, regardless of the book format. This example uses a PDF, whereas ePUB will have a longer URL in the cfi element.

"table_of_contents": [
"title": "E-book bonus materials",
"path": "/pages/403221165/content",
"level": 1,
"cfi": "/2",
"page": "2"
"title": "Contents",
"path": "/pages/403221170/content",
"level": 1,
"cfi": "/7",
"page": "7"
"title": "Chapter 1: Psychoactive Drugs: Classification and History",
"path": "/pages/403221174/content",
"level": 1,
"cfi": "/11",
"page": "11"

The base URL is "" then build your URL by adding the VBID and "/cfi" until you have "" This becomes your base URL for this request.

Now parse the response to locate your chosen location, such as Chapter 1, then append the "cfi" element until you have "" and you are now ready to utilize SSO redirects like this: 

<?xml version=\"1.0\" encoding=\"UTF-8\"?>

Error Codes

HTTP & Error messages 



Not Found

API key mismatch

Permission Denied

API key mismatch
403 Catalog not found Contact Customer Service

Product <vbid> not found.

make the default request and locate a valid vbid
404 Book not found  make the default request and locate a valid vbid 
422 Invalid currency: <currency> ISO-4217 currency code(s) 

Book is locked

TOC unavailable on this asset  

Internal Server Error



Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.