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
• Data Definitions
• Request Headers
  • Request header - default example
  • Request header - resend example
  • Request body - default example
  • Request example - resend
• Response
  • Response body - default example
  • Response body - resend example
  • Response descriptions
  • Sample default email
• Error Codes 

Verb/URI

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

Data Definitions

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

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