PUT v4/inventory/adoptions

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

PUT 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
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",
  "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 

 
403

Forbidden - API key is invalid

Do not pass as null 
422  Unprocessable Entity - too many items submitted > 25,000 items submitted
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.