The API allows for the update of a single or multiple parameters on a user record in the VitalSource Bookshelf system. This can be used to update user metadata or reset a user's password.
Verb/URI
GUID}https://api.vitalsource.com/v3/users.xml/:{
Data Definitions
This request has the same format as v3/users - Create however, passing the <redemption-code> option is not available on update. You can pass all elements on update or a single element that requires the update.
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
---|---|---|---|---|---|
reference | Message body | Unique alphanumeric, often a student number or other identifier used by the integrators system. | string | ABC_123_DEF_456 | No |
Message body | Email address of the user. Must conform to email regex format. | string | sri.krisha@univ.edu | No | |
password | Message Body | Password conforming to current VitalSource standards | string | ABC#%123DEf.45 | No |
first-name | Message body | First name of user. In an anonymous integration pass a hashed string | string | Jose | No |
last-name | Message body | Last name of user. In an anonymous integration pass a hashed string | string | Hernandez | No |
question-id | Message body | One of up to 10 security questions that can be set for a user | integer | 7 | No |
question-response | Message body | Answer to 10 security questions that can be set for a user | string | Chocolate | No |
profile-url | Message body | Used only if also redeeming a created code for a user to add a book to Bookshelf | string | http://someurl.com/profile | No |
promote-option | Message body | Opt-in/out for promotional materials | boolean | 1 | No |
survey-option | Message body | Opt-in/out for surveys about software platform and services | boolean | 1 | No |
store-url | Message body | Not usually needed | string | https://store.vitalsource.com/ | No |
notify | Message body | By default, an email notification/welcome message is sent to the user when the account is created. Suppress by setting to false. | boolean | 1 | No |
affiliate | Message body | Will appear in the organization field in VitalSource Manage. Aligns with Caliper organization | string |
Univ. of Leeds |
No |
locale | Message body | Sets the default locale language code for the Bookshelf user. Full list of valid locale language codes can be found here. | string |
es |
No |
Security Questions
Below are the fixed set of security questions offered by VitalSource. Integrators may select any combination for use. VitalSource does not support custom questions. Question ID's 1-5 are deprecated and no longer supported, except in legacy integrations.
Question ID
|
Question
|
---|---|
6 | What is your favorite sport? |
7 | What is your favorite flavor of ice cream? |
8 | What is the name of your favorite pet? |
9 | When you were young, what did you want to be when you grew up? |
10 | What was the last name of your favorite teacher? |
Request Headers
The associated user access token is a required element in the header on update
X-VitalSource-API-Key: ALLCAPSANDNUMBERS
X-VitalSource-Access-Token: lowercaseandnumbers
Content-type: text/xml
Request body - reference user example
<user>
<reference>Updated_Reference_String</reference>
<first-name>Jose</first-name>
<last-name>Tester</last-name>
</user>
Request body - full user example
<?xml version="1.0" encoding="UTF-8"?>
<user>
<password>QXZY#%123DaF.45</password>
<email>jose.hernandez2@univ.edu</email>
<first-name>Jane</first-name>
<last-name>Hernandez</last-name>
<question-id>7</question-id>
<question-response>Strawberry</question-response>
<promote-option>0</promote-option>
<survey-option>0</survey-option>
<affiliate>Univ of Leeds</affiliate>
<locale>es</locale>
</user>
Response
Response body - reference user example
<?xml version="1.0" encoding="UTF-8"?>
<user>
<email>CAPSANDNUMBERS@placeholder.1111.edu</email>
<first-name>Jose</first-name>
<last-name>Tester</last-name>
<guid>ALLCAPSANDNUMBERS</guid>
<access-token>lowercaseandnumbers</access-token>
<library>
</library>
</user>
Response body - full user example
<?xml version="1.0" encoding="UTF-8"?>
<user>
<email>jose.hernandez@univ.edu</email>
<first-name>Jose</first-name>
<last-name>Hernandez</last-name>
<guid>ALLCAPSANDNUMBERS</guid>
<access-token>lowercaseandnumbers</access-token>
<library>
</library>
</user>
Response Descriptions
Name
|
Description
|
---|---|
Confirmation of email address created | |
first-name | Confirmation of first name created |
last-name | Confirmation of last name created |
access-token | Used for subsequent calls related to this specific user. This may expire; see reset token |
guid | Globally Unique Identifier in the VitalSource system. VitalSource strongly recommends all integration customers save this field in the response payload. As we provide the ability to update all elements, including reference and your access token may change, GUID may be the only way to recover access to a user. GUID will never change. |
library | Array of all books redeemed if done within the same request and/or books the user has access to use. |
Error Codes
HTTP & Error messages
|
Message
|
Notes
|
---|---|---|
200 |
|
Success. Errors provided simultaneously |
463 |
Question is invalid |
Number must be between 1-10, inclusive. |
465 | Email can't be blank | Verify data types and requirements |
465 |
First name can't be blank |
|
465 |
Last name can't be blank |
|
465 |
Question response can't be blank |
|
465 |
Password can't be blank |
|
465 |
Password is too short |
Password conforming to current VitalSource standards |
903 |
Access token and user do not match |
Verify these elements |
482 | Malformed create user request | Verify data types and requirements |
904 |
User reference already exists |
Duplicate reference string for this API key |
907 | Insufficient requirements for user update | Verify data types and requirements |
1002 | Email is locked | Speak to your CSM to have this issue resolved |
Comments
Please sign in to leave a comment.