Patron Information API

The Patron Information API is the endpoint to hit for user-specific information and serves as the primary entry point for all of the Circulation APIs. It provides hypermedia links to the checkouts and holds endpoints, templates for the Search API and Library Availability API, and other user-specific information.

Using the Patron Information API

Using GET or PUT requests, you can use the Patron Information API to see and update user information.

Available endpoint actions

• GET user information: This request retrieves user-specific information, like lending period preferences, checkout limits, hypermedia links to other APIs, etc.
• Update a user's lending period (PUT): This request updates a user's lending period preference for a specific format.

GET user information

Send a GET request to the /v1/patrons/me endpoint to retrieve important user information, such as:

• The user's unique collectionToken (learn more in the section below).
• The user's current lendingPeriod preferences for each formatType (e.g., ebook and audiobook).
• The user's checkoutLimit (how many titles they can borrow), holdLimit (how many titles they can place on hold), and lastHoldEmail (the most recent email address they used to place a hold).
• Hypermedia links:
  • checkouts: Follow this link to access the Checkouts API.
  • holds: Follow this link to access the Holds API.
• Link templates to build URLs with the user's collectionToken:
  • search (for the Search API)
  • availability (for the Library Availability API)
• editLendingPeriod actions, which lets you update a user's preference for each format. The actions section will also show the lending period options for each format.

Here is a sample GET request to the /v1/patrons/me endpoint:

About a user's collectionToken

The collectionToken returned in the above example represents the exact digital collections that this specific user has access to. It can be used in subsequent Search API, Metadata API, and Library Availability API calls.

While you can store library and school collectionTokens for up to 30 days, we strongly recommend that you don't store user collectionTokens. User collectionTokens should be refreshed each session.

Using link templates

You can use the linkTemplates to construct requests to the Search and Library Availability APIs. The templates include the user's specific collectionToken and replaceable variables in curly braces.

Below is a sample Availability GET request built through the availability linkTemplate.

The "{reserveId}" template parameter has been replaced with the reserveId for a particular title (FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6).

The above GET request will return the availability information for the title based on the specific collection the user can access.

For more information on using the search or availability template values, see the Search API and Library Availability API pages.

Updating the user's lending periods (PUT)

If a user would like a longer or shorter lendingPeriod for each formatType, you can make individual calls to update their preference.

Each library and school decides which lending period options are available to their users, and lending period options can vary by format type. You can see the available lending periods for each format in a GET request to the Patron Information endpoint (see example above).

Here's an example PUT request to the /v1/patrons/me endpoint to update the user's ebook lending period.

When the update is successful, you'll get a response like this: