POST v3/users - Create

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.



Data Definitions

Data Type
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 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 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

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




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

Content-type: text/xml

Request body - reference user example



Response body - reference user example

<?xml version="1.0" encoding="UTF-8"?>

Response Descriptions

email Confirmation of email address created
first-name Confirmation of first name created
last-name Confirmation of last name created


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 


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 


Success. Errors provided simultaneously

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

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 
Was this article helpful?
2 out of 5 found this helpful



Please sign in to leave a comment.