This API will create a VitalBook record and optionally ingest a PDF or ePUB source file. This call begins the process of creating a VitalBook. On a successful call, the VBID (VitalBook ID) will be returned to you. This unique identifier can later be used to update the VitalBook.
Download our full Postman collection which contains pre-populated versions of all Asset APIs here.
Verb/URI
https://services.vitalbook.com/vital_books.xml
Data Definitions
The minimum fields needed to create a VBID
|
Name
|
Usage
|
Description
|
Data Type
|
Example & Details
|
Required
|
|---|---|---|---|---|---|
| api_key | Query param |
your VitalSource API key |
string | ALLCAPSANDNUMBERS | Yes |
| 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 |
Other fields
|
Name
|
Usage
|
Description
|
Data Type
|
Example & Details
|
Required
|
|---|---|---|---|---|---|
| agency_price | Query param | 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 | Query param | Author first name | string(50) | Miguel | No |
| author_last_name | Query param | Author last name | string(50) | de Cervantes | No |
| author_name | Query param | Author's full name | string(100) | Miguel de Cervantes | No |
| build_url | Query param |
|
URI | ||
| 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. |
integer |
|
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 | |
| 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 |
|
fulfillment_only |
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 |
| kind_id | Query param |
|
integer | DO NOT USE (legacy only) | No |
| next_isbn | Query param |
Additional ISBN field |
string | No | |
|
{option}_ sale_date |
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 |
|
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 |
|
rental_price_ {currency}_ {term}_days |
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 |
|
{rights}_ sales_rights |
Query param | 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 |
Query param | Allow sample codes to be generated for this title | boolean | "yes", "1", "no", "0" | No |
|
subtitle |
Query param | Subtitle | string | No | |
|
toc |
Query param | Table of contents information. **Only supported for DashML format.** | text | DO NOT USE except DashML | No |
|
url |
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
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. |
Comments
Please sign in to leave a comment.