GET v3/users/:param - Read (Verify) – VitalSource Developer Network

This API verifies the existence of a VitalSource Bookshelf account. You can use the user's email, GUID or reference to locate the account information or details. Pass a single element in the header as a parameter.

There are two versions of the response body, default and full. Default is provided to verify the existence of the user with the lowest possible latency. The full payload is designed when seeking greater detail. To gain the full payload append "?full=true" as shown in the data definitions.

Verb/URI
Data Definitions
Request Headers
Response
Error Codes

Verb/URI

GET https://api.vitalsource.com/v3/users.xml/{param}

Data Definitions

Name	Usage	Description	Data Type	Example	Required
	URL param	The default request		v3/users.xml/{guid}	Yes
email address	URL param	Email address is only valid in the case of full users where your API key is the grantor of rights.	Regex email	v3/users.xml/{email}	No
reference	URL param	Reference strings are passed during Create and can be modified via Update Definition: External user id passed in on create of user by integrator's system	string	v3/users.xml/{reference}	No
guid	URL param	Global User ID (guid) is always returned in the payload after a successful create user. Definition: VST internal id for the specific user	string	v3/users.xml/{guid}	No
?full=true	URL param	Returns additional elements in response including security questionid/response, promotion, and survey options	string	v3/users.xml/{{guid}}?full=true	No

Request Headers

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

Response

Response Body - default

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<user>
	<email>bob@XXX-***.com</email>
	<first-name>Bob</first-name>
	<last-name>Bobbington</last-name>
        <sso-only>true</sso-only>
	<require-deactivate>false</require-deactivate>
	<require-book-list-update>false</require-book-list-update>
	<store-url>http://someurl.somestore.com</store-url>
	<timestamp>20150311153046</timestamp>
	<max-desktop-activations>2</max-desktop-activations>
	<max-mobile-activations>2</max-mobile-activations>
	<email-locked>false</email-locked>
</user>

Response Body - full

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<user>
	<email>bob@XXX-***.com</email>
	<first-name>Bob</first-name>
	<last-name>Bobbington</last-name>
        <sso-only>true</sso-only>
	<require-deactivate>false</require-deactivate>
	<require-book-list-update>false</require-book-list-update>
	<store-url>http://someurl.somestore.com</store-url>
	<timestamp>20150311153046</timestamp>
	<max-desktop-activations>2</max-desktop-activations>
	<max-mobile-activations>2</max-mobile-activations>
	<email-locked>false</email-locked>
        <strong-password>true</strong-password>
       <password-updated>2020-01-01 01:00:00 UTC</password-updated>
       <locale/>
       <referral-guid>lettersandnumbers</referral-guid>
      <promote-option>false</promote-option>
      <survey-option>false</survey-option>
      <eula_accepted>true</eula_accepted>
      <eula_accepted_at>2020-01-01 18:03:51 UTC</eula_accepted_at>
      <eula_type>vitalsource</eula_type>
      <question-response>lettersandnumbers</question-response>
      <question-id>number</question-id>
      <last-brand-accessed>digital</last-brand-accessed>
      <bookshelf-preference>Online</bookshelf-preference>
      <email_verification_required>false</email_verification_required>
      <email_verification_completed>false</email_verification_completed>
      <roles>
        <role>
          <id>numbers</id>
          <name>learner</name>
          <school-id/>
          <verified>false</verified>
          <regions type="array">
  </regions>
         <institutions type="array">
          <institution>
          <assigned_institution_id>numbers</assigned_institution_id>
            <institution_id/>
            <level>1</level>
            <name/>
            </institution>
            </institutions>
            <context>Stargate</context>
       </role>
     </roles>
 </user>
</user>

Response Descriptions

Name	Description
email	Email address of the user. This is NOT for a reference user account, only for accounts with UN, PW combinations.
first-name	User's first name
last-name	User's last name
access-token	Used for subsequent calls related to this specific user
guid	Global User ID, produced at create by VitalSource and returned in payload
sso-only	True or false value; set to true if a reference-only account was created. Once a user configures his Bookshelf account with an email/password or if the account was created using email/password this will be false.

FYI; if you need an access token for a user go to the Credentials endpoint

Error Codes

HTTP & Error messages	Message	Notes
200		Success
403	403 - Forbidden	Verify API key
404	404 - Not Found	Verify params

GET v3/users/:param - Read (Verify)