POST v3/users - Create – VitalSource Developer Network

This API creates a user within the VitalSource Bookshelf ecosystem. Integrators should always create reference users.

Reference user:

App access only via one-time browser SSO (requires Internet connection)
Integrator control of account/content access

Reference user upgraded to full user:

This happens when user creates or logins with existing Bookshelf account after they are redirected via SSO to Bookshelf
User control of account access
VitalSource is privacy vendor of record

For more information on how to force a user upgrade, please see our redirects API doc here.

Verb/URI
Data Definitions
- Security Questions
Request Headers
- Request body - reference user example
Response
- Response body - reference user example
- Response descriptions
Error Codes

Verb/URI

POST https://api.vitalsource.com/v3/users.xml

Data Definitions

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	Yes
first-name	Message body	First name of user. In an anonymous integration pass a hashed string	string	Jose	Yes
last-name	Message body	Last name of user. In an anonymous integration pass a hashed string	string	Hernandez	Yes
redemption-code	Message body	An unredeemed code that you wish to add to this user's account	string	ALLCAPSANDNUMBERS	No
question-id	Message body	One of up to 5 security questions that can be set for a user	integer	7	Yes, if full user
question-response	Message body	Answer to 10 security questions that can be set for a user	string	Chocolate	Yes, if full user
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	0	No
survey-option	Message body	Opt-in/out for surveys about software platform and services	boolean	0	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	0	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

X-VitalSource-API-Key: ALLNUMBERSANDCAPS
Content-type: text/xml

Request body - reference user example

<user>
 <reference>Postman_Test_001</reference>
 <first-name>Jose</first-name>
 <last-name>Tester</last-name>
</user>

Response

Response body - reference user example

<?xml version="1.0" encoding="UTF-8"?>
<user>
 <email>lowercaseandnumbers@placeholder.1111.edu</email>
 <first-name>Jose</first-name>
 <last-name>Tester</last-name>
 <guid>ALLCAPSANDNUMBER</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. It is important to use verify credentials before using an API call that requires an access-token to ensure you have the most current value. This may be reset, for more details 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.
464	Account already exists	Email address on full user account is already taken
465	Data validation error	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
466	Your email or password was not accepted	Verify data types and requirements
482	Malformed create user request	Verify data types and requirements
904	User reference already exists	Duplicate reference string for this API key
906	Insufficient requirements for user create	Verify data types and requirements
992	API user company is misconfigured (has multiple companies)	Speak to your CSM to have this issue resolved

POST v3/users - Create