POST v3/users - Create

This API creates a user within the VitalSource Bookshelf ecosystem. VitalSource supports two equally valid types of user, reference and full user. Integrators should always create reference users even when their customers wish to use an email/pw structure. Creation of full users via integration pathways is shown here only for legacy customers.

VitalSource supports an aliasing mechanism that allows integrators to upgrade reference accounts to email/pw accounts once the user arrives at a VitalSource URL. This setup allows integrators to add and maintain access to accounts while protecting the privacy of the UN/PW entered by users. This structure is compliant with GDPR and other privacy standards.

Some integrations customers have reason to maintain reference accounts or move on to full user accounts. The list below covers the primary benefits of each type.

Full user:

  • Cross-instance portability
  • User control of account access
  • VitalSource is privacy vendor of record

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:

  • Integrator ongoing access to content provision/removal
  • 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

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, if reference user
email Message body Email address of the user. Must conform to email regex format. string sri.krisha@univ.edu Yes, if full user
password Message body Password conforming to current VitalSource standards string ABC#%123DEf.45 Yes, if full user
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 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

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
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>

Request body - full user example

<?xml version="1.0" encoding="UTF-8"?>
<user>
<password>QXZY#%123DaF.45</password>
<email>jose.hernandez@univ.edu</email>
<first-name>Jose</first-name>
<last-name>Hernandez</last-name>
<question-id>7</question-id>
<question-response>Chocolate</question-response>
<promote-option>1</promote-option>
<survey-option>1</survey-option>
<affiliate>Univ of Leeds</affiliate>
<locale>en</locale>
</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 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>AAAABBBB33333</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 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.
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 
Was this article helpful?
2 out of 5 found this helpful

Comments

0 comments

Please sign in to leave a comment.