Yindo Vendor API Help Page

Introduction

To use the Yindo Vendor API you will need a VendorKey. Contact us to obtain one. The VendorKey should be supplied to the API in a X-VendorKey header:

X-VendorKey: 11111111-2222-3333-4444-555555555555

To access specific versions of this API you will need to supply the version parameter in the accept header:

Accept: application/json; version=1

The current version is 1, the default version is 1

Account

The Account API provides vendors a means to check, create and validate accounts.
To prevent unneeded errors in the account creation process, it is advisable to validate the username before trying to create an account.

The following HTTP statuscodes will be returned in case of an error, unless otherwise stated.

400 - The required data (such as username or e-mail) was not valid or not supplied at all.
403 - The vendorkey was not supplied, or the specified method is not enabled for the vendorkey.
404 - The requested item was not found (for example a user with the supplied id does not exist for the current vendor).
417 - The processing failed due to an error, this often happens when the supplied data is not correct.
500 - An unexpected error occured, please contact us with details on your call.

API	Description
GET api/account/{username}	V1 - Checks to see if a user exists in the system by searching for a username or an e-mail address
DELETE api/account/{username}	V1 - Remove user from the database. Any existing data is maintained where possible, by linking it to an anonymous user. Only users linked to the current Vendor can be deleted. A 404 will be generated if the user is not found. A 403 will be generated if a user cannot be removed.
GET api/account/{userid}	V1 - Checks to see if a user exists in the system, by searching for a userID
GET api/account/activationtoken/{userid}	V1 - Generates a new e-mail confirmation token for the specified userID
PUT api/account/activate/{userid}	V1 - Manually activates the account with the specified userID
POST api/account	V1 - Adds a new user to the system. An empty profile is created which can be updated using the /api/profile methods on the public API. NOTE: Before the account can be used, it needs to be validated by the user through the ConfirmationCode. The vendor needs to send this code to the user and the user needs to present this code proving the validity of the users e-mail address. Once the vendor presents the ConfirmationCode to the API, the account will be unlocked.
PUT api/account	V1 - Confirms the validity of a users emailaddress using the pregenerated confirmation token.
GET api/account/reset/{userID}	V1 - Generates a password reset token for the specified user Guid
GET api/account/reset/{email}	V1 - Generates a password reset token for the user with the specified e-mail address.
PUT api/account/reset/{email}/{password}	V1 - Resets the password for the user with the specified e-mail address or username to the specified password.
PUT api/account/reset/{userid}/{password}	V1 - Resets the password for the user with the specified userid to the specified password.
GET api/account/validate/{username}/{password}	V1 - Validates a useraccount by combining the username and password. The HTTP status code is set based on the validation result: 200 - The user was found and the password matches 404 - The user was not found or the password doesn't match
GET api/account/validate/{userid}/{password}	V1 - Validates a useraccount by combining the users id and password. The HTTP status code is set based on the validation result: 200 - The user was found and the password matches 403 - The userid and password don't match 404 - The user was not found
PUT api/account/reset	V1 - Confirms the reset of a users password by validating the pregenerated confirmationcode.

Book

The Book API operates on single books, allowing you to retrieve the specifics or modify the details for a single book.

API	Description
POST api/book	V1 - Add a new book to the database.
PUT api/book	V1 - Update a book in the database.
GET api/book/titleinfo/{ean}	V1 - Gets the title info for a book, as is it available in the Yindo Aggregator (which is kept up to date based on the CB Onix feed)
GET api/book/details/{ean}	V1 - Gets the details for a book, based on the specified EAN
GET api/book/details/{ean}/uncached	V1 - Gets the details for a book, based on the specified EAN This method bypasses (and updates) the cache for this specific EAN.
GET api/book/zippng/{ean}	V1 - Gets an encrypted zipfile with a collection of PNGs for the specified EAN This method will try to retrieve a zipfile for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned. If a zipfile is available, it will be encrypted using AES-CBC, with a vendor-specific secret, and a random 256 bit salt.
GET api/book/zippngbundle/{ean}	V1 - Gets a zipfile with a collection opf PNGs for the specified EAN This method will try to retrieve a zipfile for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned.
GET api/book/zippng/{ean}/check	V1 - Tests the availability of a zipfile for the specified EAN This method will check the availability of a zipfile for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned.
GET api/book/epub/{ean}	V1 - Gets an encrypted ePub file for the specified EAN This method will try to retrieve an epub for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned. If an ePub file is available, it will be encrypted using AES-CBC, with a vendor-specific secret, and a random 256 bit salt.
GET api/book/epubbundle/{ean}	V1 - Gets an ePub file for the specified EAN This method will try to retrieve an epub for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned.
GET api/book/epub/{ean}/check	V1 - Test the availability of an encrypted ePub file for the specified EAN This method will check the availability of an epub for the specified EAN. If the EAN is not available for the vendor, a statuscode 403 will be returned.
POST api/book/epub	V1 - Decrypts an encrypted ePub file
POST api/book/zippng	V1 - Decrypts an encrypted ePub file

BookList

The BookList API operates on single booklists, allowing you to retrieve the specifics or modify the details for a single booklist.

API	Description
POST api/booklist	V1 - Add a book to a booklist
GET api/booklist/{id}	V1 - Gets the details for the specified booklist

BookLists

The BookList API operates on collections of booklists, allowing you to retrieve the specifics or modify the details for a collection of booklists.

API	Description
GET api/booklists	V1 - Gets all current booklists for the calling Vendor

Coupon

API	Description
GET api/checkcoupon/{code}	No documentation available.
GET api/coupon/{code}	No documentation available.
GET api/couponmessage/{code}	No documentation available.
PUT api/coupon/{code}/{email}	No documentation available.

Filters

The Filters API retrieves lists of filters.

API	Description
GET api/filters/agelevels	V1 - This method retrieves the available agegroups for the specified vendorkey.
GET api/filters/agelevel/{id}	V1 - This method retrieves the available agegroups for the specified vendorkey.
PUT api/filters/agelevel	V1 - This method updates the provided agelevel.
POST api/filters/agelevel	V1 - This method creates the provided agelevel.
DELETE api/filters/agelevel	V1 - This method removes the provided agelevel. NOTE: Before the selected agelevel can be deleted, all books that are currently linked to this agelevel, will be unlinked. This might result in books without any linked agelevels.
GET api/filters/categories	V1 - This method retrieves the available categories for the specified vendorkey.
GET api/filters/category/{id}	V1 - This method retrieves the category for the specified vendorkey and id.
PUT api/filters/category	V1 - This method updates the provided category.
POST api/filters/category	V1 - This method creates the provided category.
DELETE api/filters/category	V1 - This method removes the provided category. NOTE: Before the selected category can be deleted, all books that are currently linked to this category, will be unlinked. This might result in books without any linked categories.
GET api/filters/avilevels	V1 - This method retrieves the available avilevels.

Mandate

The Mandate API operates on Manadtes, Recurrences for Mandates and Trials for Mandates, allowing you to retrieve the specifics or modify the details for instances of these items.

API	Description
POST api/mandate/trial	V1 - Add a new payment trial to the database.
PUT api/mandate/trial	V1 - Update a payment trial.
PUT api/mandate	V1 - Update a payment mandate.
GET api/mandate/trial/{userID}	V1 - Gets the specific trial for the provided userID
POST api/mandate/recurrence	V1 - Add a new mandate recurrence to the database.
PUT api/mandate/recurrence	V1 - Update a payment mandate.
GET api/mandate/recurrence/{mandateID}	V1 - Gets the specific recurrence for the provided mandateID
POST api/mandate	V1 - Add a new payment mandate to the database.
GET api/mandate/{hook}	V1 - Gets the specific mandate for the provided hook
GET api/mandate/{customerID}	V1 - Gets the specific mandate for the provided customerID

Profile

The Profile API operates on the profile for a single user, allowing you to create a user or retrieve and modify user details
As opposed to the profile methods in the public API, the methods in this vendor API allow the vendor to update the subscription details.

API	Description
GET api/profile/{userID}	V1 - Gets the userprofile for the selected user.
GET api/profile/main/{userID}	V1 - Gets the main (parent) profile for the selected user.
GET api/profile/main/{userID}/child/{childID}	V1 - Gets a child profile.
GET api/profile/main/{userID}/children	V1 - Gets a list of children (if any) for the specified user.
PUT api/profile	V1 - Updates the profile for specified user.
PUT api/profile/main	V1 - Updates the main profile for the specified booqees user. As opposed to the profile methods in the public API, this method allows the vendor to update the subscription details.
POST api/profile/main/{userID}/child	V1 - Creates a child profile for the specified booqees user.
PUT api/profile/main/{userID}/child	V1 - Updates the child profile for the specified booqees user.
DELETE api/profile/main/{userID}/{childID}	V1 - Removes the child profile for the specified booqees user. Please note the profile will not actually be removed from the database. To maintain logging integrity, the link between the child profile and the parent profile is merely invalidated.

Publishers

The Publishers API operates on collections of publishers, allowing you to retrieve lists of data.

API	Description
GET api/publishers	V1 - Retrieve a list of all publishers

Search

The Search API operates on search results.

API	Description
GET api/search/log/from/{fromdate}/to/{todate}	V1 - Returns a list of search resultlogs for the specified period. Only results for the current vendor will be retrieved.

UserSession

The Session(s) API operates on sessions for a single user, allowing you to create a user or retrieve and modify user details

API	Description
GET api/usersession/{key}	V1 - Gets a the details for the specified session.
GET api/usersession/totals/{userID}	V1 - Gets the totals (books read, minutes read, etc) for a the specified user.
PUT api/usersession/{key}	V1 - Touches the specified session, therefore prolonging its lifetime.
DELETE api/usersession/{key}	V1 - Ends the specified session. Alternatively the session can be ended by loggin the user out.
DELETE api/usersession/clientkey/{key}	V1 - Ends the session identied by the supplied ClientKey. Alternatively the session can be ended by loggin the user out.
GET api/usersessions/{userID}	V1 - Gets all active sessions for the specified user.