POST v4/activation_requests - Create

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:

 

Verb/URI

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

Data Definitions

Name
Usage
Description
Data Type
Example
Required
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.vitalsource.com. If your organization has a white label version of the Bookshelf eReader (NOT the online store) then modify this URL accordingly, otherwise pass as is. URL https://bookshelf.vitalsource.com Yes
send_email    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   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

 

Resend

If you wish to resend/issue an existing activation request you can do so as follows.

Verb/URI

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

Data Definitions

Name
Usage
Description
Data Type
Example
Required
email param Email address where the activation request was sent on original activation request email regex  sri.krisha@univ.edu Yes

 

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
X-VitalSource-Access-Token: as787s7sd86s7ssrefg
Content-Type: application/json

Request body  - create example 

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

Request example - resend

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

Response

Response body - create example

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

Response body - resend example

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

Response Descriptions

Name
Description
id Unique ID of the activation request
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

 

 

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

Comments

0 comments

Please sign in to leave a comment.