The v4 Adoptions API is part of VitalSource's next-generation catalog services. It allows a bookstore, reseller or other partner to send a list of ISBNs for which they want digital matches. From this list, VST will create or update Booklist booklists and items, grant distribution rights to titles in the VST wholesale catalog, and request rights from publishers for matched items that can’t be given through wholesale. Once submitted, human users can follow progress in the Booklist application, and API clients can pull all adoptions from the company’s VST catalog.
One key feature of VST’s next-gen catalogs is the ability to tag an ISBN with parameters from the source system that are retained through the VST ecosystem and passed back to the customer in their product catalog. For example if a customer wants a match for the print ISBN 9780123456789, and VST matches that to an item in our catalog with the VBID 123456789X, it can be difficult for the consumer to know that 123456789X is our “answer” to their “question” 9780123456789. In this new system, however, the customer could tag their ISBN with the print ISBN — or a completely different attribute like a unique billable ISBN or item number. When a customer pulls their catalog, they would see that our item 123456789X would be tagged with the customer’s custom identifier, allowing the digital match to be re-joined to the originally-requested item.
Verb/URI
https://api.vitalsource.com/v4/inventory/adoptions
Data Definitions
|
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
|---|---|---|---|---|---|
|
isbn |
body | The ISBN of the title to be matched in the customer system. This can be an ISBN 10 or 13, but an ISBN 13 is preferred. | string, 32 | L-999-70461 | yes |
| term | body | Name of the term that this book has been adopted for. This is used to name a discrete booklist in Booklist Manager; if term names don’t apply to your business, you could use any other segmentation that’s appropriate. | string, 242 | Fall-2020 | yes |
| duration | body |
The specific duration of the title you want added to the booklist. Instead of receiving all durations, only the specified duration will be added, or the next largest duration that fulfills your request. Sending a -1, 0, or the word "perpetual" will add the perpetual to the booklist. |
string / integer |
"perpetual" 30 "30" |
no |
| edition | body | The edition of the title to be matched. Accepted values 0-127. In cases where VST finds multiple potential matches, this value is used by VST staff to help identify the best match. | integer | 3 | no |
| title | body | The title of the book to be matched. In cases where VST does not find a match, this value is used by VST staff to identify the book so we can try to secure rights from the publisher on your behalf. | string, 250 | A Christmas Carol | no, highly recommended |
| publisher | body | The publisher of the book to be matched. In cases where VST does not find a match, this value is used by VST staff to identify the content owner so we can try to secure rights on your behalf. | string, 100 | Originals | no |
| author | body | The full name of the author of the book to be matched. In cases where VST does not find a match, this value is used by VST staff to help identify the book so we can try to secure rights from the publisher on your behalf. | string, 100 | Charles Dickens | no, highly recommended |
| publication_date | body | The publication date of the book to be matched. In cases where VST finds multiple potential matches, this value is used by VST staff to help identify the best match. | ISO-8601 date | 2018-02-01 | no |
| prefer_courseware | body |
By default, the VST matching system will match eTexts where possible, and fall back to courseware. However, if you want to reverse this behavior, you can. Default is false. |
boolean | false | no |
|
pos_tags |
body | Array of tags that will be returned with the matched item in the customer product catalog. | array of strings, 32 | [“thing1”, “thing2”] | no |
| courses | body | If you do not include the courses node, VST will only match on VST-wholesale content. However, there is a lot of content in our system where you will need distribution rights directly from the content owner. To provide rights, publishers require extra information, which you provide in this node. | array of hashes | “courses”: [ { … }, { … } ] |
no, but required for distribution requests |
|
courses/course_code |
body | Course code | string, 255 |
BIO101 ENG 238 |
no |
|
courses/section_number |
body | Section number, if there are more than one section for the same course. | string, 255 |
001 C |
no |
|
courses/enrollment |
body |
Number of students in the class. Depending on your system, this could come from a variety of places: Projected enrollment, Class size limit, Room size, Active student enrollments Consider using multiple sources with a fallback, as requests without enrollments will not make it to publishers. |
integer |
24 |
no, but required for distribution requests |
|
courses/deadline |
body | Deadline for digital content to be matched by VST if it’s going to be used in the course. | ISO-8601 date | 2020-07-15 | no, but required for distribution requests |
|
courses/start_date |
body | Course start date. | ISO-8601 date | 2020-08-01 | no, but required for distribution requests |
Request Headers
X-VitalSource-API-Key: ALLCAPSANDNUMBERS Content-Type: application/json
Request Body
Request body - default example
[
{
"isbn": "L-999-70461",
"term": "fall2020",
"duration": "perpetual",
"edition": 2,
"title": "A Christmas Carol",
"publisher": "Hayes Barton Press",
"author": "Charles Dickens",
"publication_date": "2006-03-03",
"prefer_courseware": true,
"pos_tags": [
"L-999-70461-POS"
],
"courses": [
{
"course_code": "ABC121",
"section_number": "SEC1",
"enrollment": 15,
"deadline": "2016-01-01",
"start_date": "2016-01-01"
}
]
},
{
"isbn": "L-999-70021",
"term": "winter2020",
"edition": 1,
"title": "Common Sense",
"publisher": "Hayes Barton Press",
"author": "Thomas Paine",
"publication_date": "2006-03-04",
"prefer_courseware": false,
"pos_tags": [
"L-999-70021-POS"
],
"courses": [
{
"course_code": "ENG-102",
"section_number": "001",
"enrollment": 26,
"deadline": "2016-01-01",
"start_date": "2016-01-01"
},
{
"course_code": "ENG-102",
"section_number": "002",
"enrollment": 26,
"deadline": "2016-01-01",
"start_date": "2016-01-01"
}
]
}
]
Response
Response body - default example
Adoptions accepted
Response descriptions
|
Name
|
Description
|
|---|---|
| Adoptions accepted | You adoption(s) has been successfully accepted |
| Request body was not parseable or not array | Your submission contains errors |
Error Codes
|
HTTP & Error messages
|
Message
|
Notes
|
|---|---|---|
| 200 |
OK |
Accepted |
| 400 |
Bad Request |
Request body was not parseable or not array |
| 403 |
Execute access forbidden |
Wrong or invalid API Key |
| 422 | Unprocessable Entity - too many items submitted | > 25,000 items submitted |
Comments
Article is closed for comments.