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 to request a new link/email. Links are good for 6 weeks.



Data Definitions

Data Type
  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 Yes
brand-destination-url Message body Always pass 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.


Note: this is the required destination URL for activation requests unless you have a branded eReader site.

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





Request Headers

X-VitalSource-Access-Token: lowercaseandnumbers
Accept: application/json

Request Header - default example


Response Header - resend example


Request body  - default & resend example 

"activation_request" : {
"email": "{{vst_email}}",
"brand_destination_url": "",
"send_email": false



Response body - default example

HTTP Code: 201 Created
"email": “”,
"send_email": true,
"status": "Notification sent",
"brand_destination_url": "",
"activation_url": "",
"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
"email": “”,
"send_email": true,
"status": "Notification sent",
"brand_destination_url": "",
"activation_url": "",
"expires_at": "Wed, 01 Jan 2019 12:00:00 +0000",
"activated_at": null,
"notification_sent_at": null

Response Descriptions

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 


Success. Errors provided simultaneously

Execute access forbidden

Wrong or invalid API Key
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



Article is closed for comments.