POST v4/activation_requests - Create

This API is designed to invite new users to join the Bookshelf ecosystem via receipt of a unique email. The API will send a token that attaches the account to the link. Links are valid for 6 weeks but can only be clicked on once before expiring.

Integrators who are considering activation links should use logic prior to their generation. 

  1. Do not send a link to existing users with current full Bookshelf accounts (username/password) who have confirmed access, but rather redirect them to https://bookshelf.vitalsource.com or your branded Bookshelf site. I.e. https://full-bookshelf.vitalsource.com
  2. Delay generation of activation links until the end of your workflow.
    • If you are redeeming multiple content items into accounts (full or reference) you only need generate one activation link per user. Links associate to Bookshelf accounts and can surface all redeemed content, even multiple items.
  3. Reference accounts will be merged/aliased by VitalSource at our activation page when the user clicks the activation link. Here is a quick example: 
    • User acquires 3 books on your site. You place these three books in a reference account. You send an activation link to this user and associate the reference account to the link as part of this request.
    • The user has an existing full (username/password) account at VitalSource Bookshelf containing 7 books.
    • User receives your (single) activation link and clicks through to the VitalSource Activation page. Upon arrival the 3 book reference account is ready to be upgraded or merged.
    • User is asked to enter an email address. When the user enters an address associated with an existing account the user is recognized and after authentication the reference account is merged into the existing full account.
    • User finds they now have 10 books in their core/existing account.
      • There is no limit to the number of times this process can occur
  4. Only generate one activation link per user.
    • Do not send one link per item of content.
  5. If the same customer returns to your site and purchases a new/additional item, you have a few choices, none of which should involve using the new link Create feature with the original account.
    • Add the newly purchased content to their existing account and then use resend to generate a new link
    • Add the newly purchased content to their existing account and then send them an email notification that the content has been added to their account.

Email integration notes

As described in the response body, the links sent by VitalSource are designed to detect "status." Some customer email setups are known to interrogate/explode these links and render them useless. Please contact your VitalSource Integration Manager should reports of significant number of links arriving "expired" occur within one domain. VitalSource can advise your customer as to expeditious steps to remove this from happening. 

Note: Links are only good for a one-time use. If clicked a second time, user will be redirected to https://bookshelf.vitalsource.com/#/user/activation to request a new link/email. Links are good for 6 weeks.

Verb/URI

POST https://api.vitalsource.com/v4/activation_requests

Data Definitions

Name
Usage
Description
Data Type
Example
Required
  URL param The default request string  v4/activation_requests Yes
email Message body Email address where the activation request will be sent if the send_email parameter is set too true, otherwise this can be associated to a user for lookup purposes later. This is a loose association of an email address to a user. It is used to simply send a one-time activation link to a user who can then sign up with a different email or user account. email regex  sri.krisha@univ.edu Yes
brand-destination-url Message body Always pass

https://bookshelf-activate.vitalsource.com. This ensures the user creates a full Bookshelf account and can access their materials again in the future.

If your organization has a custom Branded Bookshelf verify full users are required and then modify the Brand URL to your custom Brand URL.

URL

https://bookshelf-activate.vitalsource.com

Yes
send_email URL param   True/false value, recommend setting this to false and using your own company specific branded emails. Email is plain-text. string  false  No
email/resend URL param  If you need to re-submit any of the above elements for change or simply resend the activation link follow the resend format POST

https://api.vitalsource.com/v4/

activation_requests/:email/resend

No

 

 

Request Headers

X-VitalSource-API-Key: ALLNUMBERSANDCAPS
X-VitalSource-Access-Token: lowercaseandnumbers
Accept: application/json

Request Header - default example

POST https://api.vitalsource.com/v4/activation_requests

Response Header - resend example

POST https://api.vitalsource.com/v4/activation_requests/{{variable_email}}/resend

Request body  - default & resend example 

{
"activation_request" : {
"email": "{{vst_email}}",
"brand_destination_url": "https://bookshelf-activate.vitalsource.com",
"send_email": false
}
}

 

Response

Response body - default example

HTTP Code: 201 Created
{
"id": "ORIGINAL_ACTIVATION_ID",
"email": “sri.krisha@univ.edu”,
"send_email": true,
"status": "Notification sent",
"brand_destination_url": "https://bookshelf-activate.vitalsource.com",
"activation_url": "https://api.vitalsource.com/v4/activation_requests/ORIGINAL_ACTIVATION_ID/activate",
"expires_at": "Wed, 01 Jan 2019 12:00:00 +0000",
"activated_at": null,
"notification_sent_at": null
}

Response body - resend example

HTTP Code: 200 Ok
{
"id": "NEW_ACTIVATION_ID",
"email": “sri.krisha@univ.edu”,
"send_email": true,
"status": "Notification sent",
"brand_destination_url": "https://bookshelf-activate.vitalsource.com",
"activation_url": "https://api.vitalsource.com/v4/activation_requests/NEW_ACTIVATION_ID/activate",
"expires_at": "Wed, 01 Jan 2019 12:00:00 +0000",
"activated_at": null,
"notification_sent_at": null
}

Response Descriptions

Name
Description
id Unique ID of the activation request. Resend creates a new ID.
email Email provided on request
send_email Send email parameter provided on request
status Status of the link, values are Created, Notification Sent, Activated, Expired. Links clicked will be marked as Activated, after 6 weeks links will expire.) Expired users can request a new link at the activation page.
brand_destination_url URL for the bookshelf reader where the user will be sent on click.
activation_url Activation URL that can be used for a one-time click access into users Bookshelf account
expires_at When the activation_url expires.
activated_at When the link was clicked, if nil it hasn't been clicked.
notification_sent When the email was sent, this is done asynchronously so it may be nil on first response.

 

Sample default email

Thank you for your purchase! In order to access your digital content, please click on the link below and follow the steps to set up your account. If you've already set up your account, you'll go straight to your digital content library.

This link is good for one use only and will expire in about six weeks.

For support, please follow the Support link in your digital content library.

Error Codes

HTTP & Error messages 
Message
Notes
201

Created

Success. Errors provided simultaneously
403

Permission Denied

Insufficient rights assigned to this API key, or error with your submission.
422 Unprocessable Entity
Error: User conflicts with an existing email and brand_destination_url in
another activation request.

The 422 error happens when:

  • sending the same person an activation link for two different accounts (The same email address is used with two different access tokens)
  • sending the same activation link to two users (The same access token is used with two different emails.)
 422 Unprocessable Entity

You will receive a 422 if one of your body parameters is invalid. Please parse payload in these circumstances.

422 "User:", "must exist, can't be blank" The access token is not associated with this API key
422 "User ID":, "can't be blank" The access token is not associated with this API key
422 System user must exist API key required
422 System user can't be blank API key required

 

 

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

Comments

0 comments

Please sign in to leave a comment.