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.  

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   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.
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.