POST v4/activation_requests - Create – VitalSource Developer Network

Use this API to send a one time activation link to a specific user for access to VitalSource Bookshelf. You can create multiple activation links for the same user/email/brand url combination, as long as a users access token is provided. The only validation is that the email address being provided is unique for a given user (access token) within the requesting institution/API key combination. If you have existing email templates, you can insert the activation link into your templates (set send_email to false). If not, VitalSource can send a plain-text email with an activation link to the user.

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

Verb/URI
Data Definitions
Request Headers
Response
Error Codes

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 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 Notification Sent, Activated, Expired. Links clicked will be marked as Activated, links expired (after 6 weeks) will be marked as Expired you can always re-request a new link.
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

TO: <send_email>
FROM: no-reply@vitalsource.com
Hi <first-name> <last-name>,
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.

<activation_url>

*This link is good for one use and will expire after 6 weeks. For Support, please follow the Support link within your digital content library.

Error Codes

HTTP & Error messages	Message	Notes
200		Success. Errors provided simultaneously
403	Permission Denied	Insufficient rights assigned to this API key, or error with your submission.
422	User must exist	Verify the user account
422	User can't be blank	Verify the user account
422	System user must exist	API key required
422	System user can't be blank	API key required

POST v4/activation_requests - Create