POST v4/activation_requests - Create

This API is designed to invite new users to join the Bookshelf ecosystem via receipt of a unique URL. 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. 

• Multiple activation emails (as in one per item) can confuse users into believing they must complete the whole activation process multiple times. Delay generation of activation links until the end of your workflow, if at all possible.
  • If your workflow requires one link per transaction, during the workflow, activation links will still succeed but you should ensure that users are not confused by the language of the email.
    • Be sure to tell users they must only complete their account once to have access to all content purchased.
• 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
• If the same customer returns to your site and purchases a new/additional item you can follow either of these pathways
  • Add the newly purchased content to their existing reference account and then generate a new link to this email address. The content will alias to the underlying full account automatically via the access token.
  • Create a new reference account and send a new link to the email address. The user will need to sign-in to merge the accounts and connect them.

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