PUT v3/users/:param - Update

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

PUT https://api.vitalsource.com/v3/users.xml/:{parameter}

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
email 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
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

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>
<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
email 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 

 

 

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

Comments

0 comments

Please sign in to leave a comment.