PUT /vital_books/:vbid - Update

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.  


PUT https://services.vitalbook.com/vital_books/:VBID

Data Definitions

The minimum fields needed to create/update a VBID 

Data Type
Example & Details
api_key Query param

your VitalSource API key

imprint_id Query param

Your publisher imprint ID from VitalSource Manage. This will place the asset into the imprint and ease distribution.

Your CSM can assist with imprint IDs

integer  10015 No, highly recommended 
isbn Query param 

Allows a unique identifier to be assigned. A fallback unique identifier (EAN) will be assigned if this field is missing. VitalSource does not allow duplicates in this field.

string, only A-Z, 0-9 and "-" L-999-70049 No, highly recommended 
title  Query param 

Title of asset (250 character limit)

string  Great Expectations  Yes


Remaining fields

Data Type
Example & Details
agency_price Query param    decimal  10.50  No
author_first_name Query param Author first name string Miguel No
author_last_name Query param Author last name string de Cervantes No
author_name Query param Author name string Miguel de Cervantes No
build_url Query param


callback_url Query param 

A URL where status updates will be posted

URI https://yourdomain.com No
companion_url Query param


URI https://yourdomain.com No 
content_type Query param

Warning this field takes precedence over kind_id.

string  book, chapter, custom, dictionary, journal, manual, question answer, reference No
copy_paste_limit Query param

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 Query param

Year of copyright

string 1605  
currency Query param

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 Query param

Description of title

bigtext Many words No
digital_list_price Query param

Formatted as a number, the list price for contract terms

decimal    No 
email Query param

**Deprecated Email address of the Bookshelf user who is creating this VitalBook.**

email regex  DO NOT USE (legacy only)  XX 
eisbn  Query param 

ISBN used for electronic title; Note that this will not set the VBID

string  L-999-70049 No 
edition Query param

A number from 0-127; the title’s edition number

integer 2 No 
faculty_review_only Query param

Sampling setting

boolean  "yes", "1", "no", "0" No
fpid Query param

The formal product identifier for the CourseSmart system

string DO NOT USE (legacy only)  No


Query param

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 




Query param 

Available stores are US, UK, AU. For UK and AU pass as a variable the locations ("uk_", "au_"). If using the US store the location variable should be "", which is a null and would produce "in_store". All permutations can be passed.

boolean "in_au_store=0" or "in_store=1" The 2nd of these would permit US sales. No
kind_id Query param


integer DO NOT USE (legacy only) No
next_isbn Query param

Additional ISBN field

string   No



Query param 

Pass as a variable of the available options ("on_", "off_"). All permutations can be passed.

date  "on_sale_date=2014-07-10" or "off_sale_date=2019-12-31"   No
online_resource_login_url Query param Online Resource Login URL (URL) publisher-hosted URL to redeem access code. URI   No
parent_isbn Query param ISBN of parent material, especially for a chapter string  978-3-598-21502-5  No 
previous_isbn Query param ISBN of prior versions string 978-3-598-21502-5   No
price Query param **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 Query param ISBN used for the printed title string 978-3-598-21502-5 No
print_limit Query param 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 Query param  Price of the printed title decimal  45.00  No
publication_date Query param Date title was published string  Later versions of our APIs might require YYYY-MM-DD format No




Query param 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 



Query param Pass as a variable of the available options (exclusive, non_exclusive, no). All permutations can be passed. ISO-3166-1 




The list of codes to use is here



Query param Allow sample codes to be generated for this title  boolean  "yes", "1", "no", "0"  No


Query param Subtitle  string   No


Query param  Table of contents information. **Only supported for DashML format.**  text  DO NOT USE except DashML   No


Query param  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)



Request header - default example (using cURL)

curl -X POST \
https://services.vitalbook.com/vital_books \
-H 'Accept: */*' \
-H 'Host: services.vitalbook.com' \
-d 'api_key={{Your-API-Key}}&title=Great%20Expectations&isbn=L-999-70049&imprint_id=100' 


Response body - default

<?xml version="1.0" encoding="UTF-8"?>
<vital_book vbid="L-999-70049">
<title>Great Expectations</title>

Response Descriptions

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 


The build process was successful and the book is ready.

The api_key is incorrect or does not have the proper permissions to access this service


User was not found


Error creating the VitalBook

Verify required fields

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.

Could not retrieve the source file

VitalSource was not able to download the source file from the given url.
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.