POST /vital_books - Create VitalSource Book (VBID)

Description

Creates a VitalBook record and optionally ingests 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.

HTTP Verbs and URLs

POST /vital_books.xml?api_key=MY_API_KEY&title=The%20Title&digital_list_price=5.99

Required Fields

Parameter
Description
Required

api_key

Your API key

Yes

title

A URI-Encoded title (Section 2 of RFC 3986 : https://www.ietf.org/rfc/rfc3986.txt)

Yes

isbn

Allows a unique identifier to be assigned. 

No, recommended

imprint_id

The logical grouping of assets within your company, called an imprint. VitalSource supports more than one imprint per company, but imprints cannot span across companies. 

 No, recommended

Recommended Fields

These fields may technically be omitted, but it is preferable to include both when calling the VitalBook Create service.

Parameter
Description
Type

isbn

Allows a unique identifier to be assigned. It is strongly recommended you include the isbn parameter, though a fallback unique identifier (EAN) will be assigned if this field is missing. (Letters, numbers and dashes and the only allowed)

Letters, numbers and dashes ONLY

I.e. L-999-70867

imprint_id

I.e. 99999

A numeric field, the ID number of the imprint which the asset should be created under. It is strongly recommended you include the imprint_id parameter. 

Every company/instance has at least one "imprint" in the VitalSource system. To find your imprint_id login to VitalSource Manage and look up available imprint(s). The ID is the number at the end of the URL as shown: https://manage.vitalsource.com/imprints/99999/

Your company’s customer success manager will need to provide you the correct ID values.

Optional Fields

Parameter
Description

digital_list_price

Formatted as a number, the list price for contract terms

email

Email address of the Bookshelf user who is creating this VitalBook. This field is not used in reference type (many LMS) implementations.

callback_url

A URL where status updates will be posted

url

A URL where the source file of this title resides awaiting conversion, which should conform to URI syntax.

description

Description of title

author

Author name; first and last name will be inferred

author_name

Author name; first and last name will not be inferred and should be specified using author_first_name and author_last_name

author_first_name

Author first name

author_last_name

Author last name

edition

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

print_isbn

ISBN used for the printed title

parent_isbn

ISBN of parent material, especially for a chapter

content_type

Valid options: book, chapter, custom, dictionary, journal, manual, question answer, reference

eisbn

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

onsaledate

Type = STRING.  Later versions of our APIs might require YYYY-MM-DD format. This is used to determine when items are available and accessible for distribution via the VitalSource store and reseller catalogs.

publication_date Date title was published; must be in YYYY-MM-DD format

sampling_allowed

Allow sample codes to be generated for this title (1=true; 0=false)

copy_paste_limit

A DRM setting of how many pages a user may copy at once. -1 provides unlimited coping and pasting. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.

print_limit

A DRM setting of how many pages a user may print at once. -1 provides unlimited printing. Values of 0 and 1 are not allowed. Otherwise the value should be 2 or greater.

in_store

Sell the perpetual product in the VitalSource store. Requires a non-zero digital_list_price to be set

in_uk_store Sell title in UK VitalSource Store. Requires GBP store_price to be supplied
bisac_code

Specify BISAC category for asset

print_price

Price of printed title

currency

Three-character currency code. USD, GBP, or AUD currently accepted. This will be applied to all price fields included in the API call. 

rental_price_usd_90_days USD Price for 90-day rental term; supplying this parameter will create the rental product of this duration
rental_price_gbp_90_days

GBP Price for 90-day rental term; supplying this parameter will create the rental product of this duration (if not preexisting)

rental_price_usd_120_days

USD Price for 120-day rental term; supplying this parameter will create the rental product of this duration

rental_price_gbp_120_days

GBP Price for 120-day rental term; supplying this parameter will create the rental product of this duration (if not pre-existing)

rental_price_usd_180_days

USD Price for 180-day rental term; supplying this parameter will create the rental product of this duration

rental_price_gbp_180_days

GBP Price for 180-day rental term; supplying this parameter will create the rental product of this duration (if not preexisting)

rental_price_usd_365_days

USD Price for 365-day rental term; supplying this parameter will create the rental product of this duration

rental_price_gbp_365_days

GBP Price for 365-day rental term; supplying this parameter will create the rental product of this duration (if not preexisting)

rental_price_usd_730_days

USD Price for 730-day rental term; supplying this parameter will create the rental product of this duration

rental_price_gbp_730_days

GBP Price for 730-day rental term; supplying this parameter will create the rental product of this duration (if not preexisting)

fpid The formal product identifier for the CourseSmart system.
faculty_review_only

Describes the asset as available for instructor sampling only, and indicates that the presentation of the content gets special treatment (e.g.: watermark). Typically the FRO flag is later removed when the publisher clears digital rights and the title becomes saleable. (1=true; 0=false)

fulfillment_only Denotes that an asset is not available in any store, nor discoverable in any public catalog.(1=true; 0=false)
copyright_year Four-digit year of copyright
classifications[][classification] The subject code for the CourseSmart/Vital Source higher education course taxonomy, e.g.: cs.bus_ecn.bus_math.bus_math
asset_additional_isbns[][additional_isbn] Additional ISBN-10 (10-Digit ISBN) or Additional ISBN-13 (13-Digit ISBN) with or without dashes. Publishers may submit additional identifiers to an asset record to facilitate search. This is typically an alternative alias Print ISBN.
asset_additional_isbns[][isbn_type] Identifies which type of additional ISBN is being passed. Type 1 indicates an ISBN-10, and Type 2 indicates an ISBN-13.
online_resource_standalone

Online Resource Standalone (T/F) denotes that the product provides access to a publisher-hosted protected website.

online_resource_saleable Online Resource Saleable (T/F) denotes that the access to the publisher-hosted protected website has a price associated.
online_resource_price_allocation Online Resource Price Allocation (integer) denotes the percentage of the total price of the product that is allocated to the access to the publisher-hosted protected website.
online_resource_login_url Online Resource Login URL (URL) publisher-hosted URL to redeem access code.
online_resource_access_description Online Resource Access Description (free text) describes how long the access code will be redeemable on the publisher-hosted website.
online_resource_course_instance Online Resource Course Instance (T/F) denotes whether additional information is required from the instructor to access the premium content.
online_resource_alternate_format Online Resource Alternate Format (free text) denotes whether the publisher-hosted protected website includes access to a publisher-format eBook.
online_resource_online_resource_id Online Resource ID (integer) provides the publisher with the option to supply an identifier for the access-protected component.
exclusive_sales_rights A comma delimited list of country codes with exclusive sales rights.
non_exclusive_sales_rights A comma delimited list of country codes with non-exclusive sales rights.
no_sales_rights  A comma delimited list of country codes with no sales rights.

Deprecated Fields

 

These fields will not trigger a failure (in order to support legacy integrations), but are not recommended for future use.

Parameter
Description

price

Formatted as a number, deprecated in favor of 'digital_list_price', populates both store_price and digital_list_price when specified

toc

Table of contents information. Only supported for DashML format.

Response Fields

Parameter
Description

vbk_format

The marketing term for the VBK Type, "page_fidelity" for PDF source, "ePub" for EPUB 2/3 source

HTTP Status Codes

Code

Message

200

OK

403 Forbidden

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, most likely a missing title

 

Success Response
<?xml version="1.0" encoding="UTF-8"?>
<vital_book>
  <vbid>L-999-99999</vbid>
  <build_status>pending</build_status>
  <title>Economics 101</title>
  <price>7.0</price>
  <store_price>7.0</store_price>
  <digital_list_price>7.0</digital_list_price>
  <vbk_format>page_fidelity</vbk_format>
</vital_book>

 

Failure Response
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Title can't be blank</error>
</errors>

Callbacks

If a callback_url parameter is present, one of the three following status updates will be posted to the given url:

  1. Success. The build process was successful and the book is ready.
    • <status id="978123467890" code="200">Success</status>
  2. 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.
    • <status id="978123467890" code="500">Could not process the source file</status>
  3. Could not retrieve the source file. VitalSource was not able to download the source file from the given url.
    • <status id="978123467890" code="500">Could not retrieve the source file</status>

Example 'curl' command

$ curl https://services.vitalbook.com/vital_books.xml?api_key=YOUR_API_KEY -d "title=The%20Discovery%20of%20Guiana&author_name=Sir%20Walter%20Raleigh&author_first_name=Walter&author_last_name=Raleigh&edition=2"

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

Comments

0 comments

Please sign in to leave a comment.