PUT /vital_books/:vbid - Update – VitalSource Developer Network

This API will update a VitalBook record. PUT request either changes metadata fields and/or or adds URL to ingest an updated version of the asset. If you include a URL parameter for a new source file, the VitalBook will need to be rebuilt. This process involves a build queue, so it may take several minutes for the book to be built, depending on what is in the queue.

Download our full Postman collection which contains pre-populated versions of all Asset APIs here.

Verb/URI
Data Definitions
Request Headers
- Request header - default example (using urlencoded)
- Request header - default example (using cURL)
Response
- Response body - default
- Response descriptions
Error Codes

Verb/URI

PUT https://services.vitalbook.com/vital_books/:VBID?api_key={{api_key}}

Data Definitions

The minimum fields needed to update a VBID

Name

Usage

Description

Data Type

Example & Details

Required

api_key

Query param

your VitalSource API key

string

ALLCAPSANDNUMBERS

Yes

vbid

Query param

The unique VBID assigned to your asset in VitalSource Manage. Supply the VBID as part of the URL path when calling the API.

Example: /vital_books/L-999-70049

integer

L-999-70049

Yes

Remaining fields

Name	Usage	Description	Data Type	Example & Details	Required
agency_price	Request body	This is a fixed price to consumer set by the publishers. Your company must transact at this price. No markup or discount on this price is allowed.	decimal	10.50	No
author_first_name	Request body	Author first name	string	Miguel	No
author_last_name	Request body	Author last name	string	de Cervantes	No
author_name	Request body	Author name	string	Miguel de Cervantes	No
build_url	Request body		URI		No
callback_url	Request body	A URL where status updates will be posted	URI	https://yourdomain.com	No
companion_url	Request body		URI	https://yourdomain.com	No
content_type	Request body	Warning this field takes precedence over kind_id.	string	book, chapter, custom, dictionary, journal, manual, question answer, reference	No
copy_paste_limit	Request body	A DRM setting of how many pages a user may copy at once.	decimal	-1 provides unlimited coping and pasting. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.	No
copyright_year	Request body	Year of copyright	string	1605	No
currency	Request body	Three-character currency code. This will be applied to all price fields included in the API call.	string: decimal	USD, GBP, or AUD currently accepted	No
description	Request body	Description of title	bigtext	Many words	No
digital_list_price	Request body	Formatted as a number, the list price for contract terms	decimal		No
email	Request body	**Deprecated Email address of the Bookshelf user who is creating this VitalBook.**	email regex	DO NOT USE (legacy only)	XX
eisbn	Request body	ISBN used for electronic title; Note that this will not set the VBID	string	L-999-70049	No
edition	Request body	A number from 0-127; the title’s edition number	integer	2	No
faculty_review_only	Request body	Sampling setting	boolean	"yes", "1", "no", "0"	No
fpid	Request body	The formal product identifier for the CourseSmart system	string	DO NOT USE (legacy only)	No
fulfillment_only	Request body	Denotes that an asset is not available in any store, nor discoverable in any public catalog.(1=true; 0=false)	boolean	"yes", "1", "no", "0"	No
imprint_id	Request body	Your publisher imprint ID from VitalSource Manage. Changing the imprint ID for a title that already exists will cause it to inherit the pricing and distribution rules of the new imprint.	integer	10015	No
kind_id	Request body		integer	DO NOT USE (legacy only)	No
next_isbn	Request body	Additional ISBN field	string		No
{option}saledate	Request body	Pass as a variable of the available options ("on", "off"). All permutations can be passed.	date	"onsaledate=2014-07-10" or "offsaledate=2019-12-31"	No
online_resource_login_url	Request body	Online Resource Login URL (URL) publisher-hosted URL to redeem access code.	URI		No
parent_isbn	Request body	ISBN of parent material, especially for a chapter	string	978-3-598-21502-5	No
previous_isbn	Request body	ISBN of prior versions	string	978-3-598-21502-5	No
price	Request body	**Deprecated in favor of 'digital_list_price', this field populates both store_price and digital_list_price when passed **	decimal	DO NOT USE (legacy only)	XX
print_isbn	Request body	ISBN used for the printed title	string	978-3-598-21502-5	No
print_limit	Request body	A DRM setting of how many pages a user may print at once.	integer	-1 provides unlimited coping and pasting. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.	No
print_price	Request body	Price of the printed title	decimal	45.00	No
publication_date	Request body	Date title was published	string	Later versions of our APIs might require YYYY-MM-DD format	No
rental_price_ {currency}_ {term}_days	Request body	Pass as a variable of the available currencies (usd, gbp, aud) and the available rental terms (90, 120, 180, 365, 730) All permutations can be passed.	decimal	"rental_price_usd_90_days=15.00" or "rental_price_gbp_730_days=45.00"	No
{rights}_ sales_rights	Request body	Pass as a variable of the available options (exclusive, non_exclusive, no). All permutations can be passed.	ISO-3166-1	"exclusive_sales_rights=FR" or "no_sales_rights=CA" The list of codes to use is here	No
sampling_allowed	Request body	Allow sample codes to be generated for this title	boolean	"yes", "1", "no", "0"	No
subtitle	Request body	Subtitle	string		No
title	Request body	Title of asset (250 character limit)	string	Great Expectations	No
toc	Request body	Table of contents information. Only supported for DashML format.	text	DO NOT USE except DashML	No
url	Request body	A URL where the source file of this title resides awaiting conversion, which should conform to URI syntax.	URI		No

Request Headers

Content-Type: application/x-www-form-urlencoded

Request header - default example (using urlencoded)

Screen_Shot_2022-11-28_at_1.59.31_PM.png

Request header - default example (using cURL)

curl -X PUT \
  'https://services.vitalbook.com/vital_books/L-999-70049.xml?api_key={{api_key}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'title=Great Expectations' \
  --data-urlencode 'imprint_id=100'

Response

Response body - default


<?xml version="1.0" encoding="UTF-8"?>
<vital_book vbid="L-999-70049">
 <build_status>approved</build_status>
 <title>Great Expectations</title>
 <price/>
 <store_price/>
 <digital_list_price>10.0</digital_list_price>
 <edition>5</edition>
 <imprint_id>100</imprint_id>
 <vbk_format>page_fidelity2</vbk_format>
 <fpid/>
 <faculty_review_only>0</faculty_review_only>
 <fulfillment_only>0</fulfillment_only>
 <classifications>
  <course_category>cs.prof_univ.edu.curri_instr</course_category>
 </classifications>
 <asset_additional_isbns>
  <asset_additional_isbn>
</vital_book>

Response Descriptions

Name	Description
build_status	Response from the VitalSource build system
title	Title sent with asset
price	Price sent with asset, if applicable
store_price	VitalSource store price of asset, if applicable
digital_list_price	DLP sent with asset, if applicable
edition	current edition of asset
vbk_format	digital format of asset. (Note: page_fidelity is the official name for PDF)

Error Codes (including callback_url)

HTTP & Error messages	Message	Notes
200	Success	The build process was successful and the book is ready.
403	The api_key is incorrect or does not have the proper permissions to access this service
404	User was not found
500	Error creating the VitalBook	Verify required fields
500	Could not process the source file	VitalSource was able to download the source file, but we were unable to process the file. This may be caused by formatting issues with the PDF/EPUB or file corruption.
500	Could not retrieve the source file	VitalSource was not able to download the source file from the given url.

PUT /vital_books/:vbid - Update