Patron Information API
The Patron Information API is the endpoint to hit for patron-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 and Library Availability APIs, and other patron-specific information.
Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com. For more information on the integration environment, please see our Getting started guide.
Using the Patron Information API
Using GET or PUT requests, you can use the Patron Information API to do the following:
Available endpoint actions
- GET patron information: Make this request to retrieve patron-specific information, like lending period preferences, checkout limits, hypermedia links to other APIs, etc.
- Update a patron's lending period: Use a PUT request to update a patron's lending period preferences.
GET patron information
Send a GET request to /v1/patrons/me endpoint to retrieve important patron 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 patron's collectionToken:
- search (for the Search API)
- availability (for the Library Availability API)
- editLendingPeriod actions, which lets you update a user's preference for format. The actions section will also spell out the specific lending period options for each format.
Here is a sample GET request to the "/v1/patrons/me" endpoint:
GET https://patron.api.overdrive.com/v1/patrons/me
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
The GET response will look something like this:
200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 2087
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 08 Nov 2022 19:13:09 GMT
Expires: -1
{
"patronId": 892911,
"websiteId": 9,
"existingPatron": true,
"collectionToken": "v1P2BAwAAAMMEAAA18",
"holdLimit": 20,
"lastHoldEmail": "yourEmailHere@overdrive.com",
"checkoutLimit": 100,
"lendingPeriods": [
{
"formatType": "eBook",
"lendingPeriod": 21,
"units": "days"
},
{
"formatType": "Audiobook",
"lendingPeriod": 21,
"units": "days"
}
],
"links": {
"self": {
"href": "https://patron.api.overdrive.com/v1/patrons/me",
"type": "application/vnd.overdrive.circulation.api+json"
},
"checkouts": {
"href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts",
"type": "application/vnd.overdrive.circulation.api+json"
},
"holds": {
"href": "https://patron.api.overdrive.com/v1/patrons/me/holds",
"type": "application/vnd.overdrive.circulation.api+json"
}
},
"linkTemplates": {
"search": {
"href": "https://api.overdrive.com/v1/collections/v1P2BAwAAAMMEAAA18/products/?q={keyword}&limit={limit}&offset={offset}&formats={formats}&sort={sort}&availability={availability}",
"type": "application/vnd.overdrive.api+json"
},
"availability": {
"href": "https://api.overdrive.com/v1/collections/v1P2BAwAAAMMEAAA18/products/{reserveId}/availability",
"type": "application/vnd.overdrive.api+json"
}
},
"actions": [
{
"editLendingPeriod": {
"href": "https://patron.api.overdrive.com/v1/patrons/me",
"type": "application/vnd.overdrive.circulation.api+json",
"method": "PUT",
"fields": [
{
"name": "formatClass",
"type": "text",
"value": "eBook",
"optional": false
},
{
"name": "lendingPeriodDays",
"type": "number",
"options": [
"1",
"7",
"14",
"21",
"89"
],
"optional": false
}
]
}
},
{
"editLendingPeriod": {
"href": "https://patron.api.overdrive.com/v1/patrons/me",
"type": "application/vnd.overdrive.circulation.api+json",
"method": "PUT",
"fields": [
{
"name": "formatClass",
"type": "text",
"value": "Audiobook",
"optional": false
},
{
"name": "lendingPeriodDays",
"type": "number",
"options": [
"1",
"7",
"14",
"21"
],
"optional": false
}
]
}
}
]
}
The collection token
The collectionToken element returned in the above example can be used in subsequent Search, Metadata, and Library Availability API calls. It represents the exact digital collections that this specific patron has access to.
Although not a common occurrence, the collections that a patron has access to do have the potential to change over time for a given library. As a result, the collectionToken can also change for a patron. The "/v1/patrons/me" endpoint will always have the up-to-date collection token for the patron. We recommend that you either: do not cache patron collection tokens or, if you must, cache the collection token only for a short period of time.
Using link templates
The best way to use the collectionToken is to make use of the provided linkTemplates. Link templates offload the proper URL construction for API requests to OverDrive server-side code. You can find these in the example GET response above under the linkTemplates element.
These templates provide Search and Availability URLs with replaceable variables placed within curly braces {just like this}. The values should be replaced with URI-safe string values so the template can be converted into a valid URI. The Patron Information API link templates should generally conform to the IETF "URI Template" Proposed Standard.
Below is a sample Availability GET request built through the availability linkTemplate.
GET https://api.overdrive.com/v1/collections/v1P1BBQ0AAA23/products/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/availability
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: api.overdrive.com
Note that the "{reserveId}" template parameter has been replaced with the reserveId for a particular title ("FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6," in this case). You can also use the title's crossRefId for this parameter.
The above GET request will return the availability information for the title based on a collection that a user is allowed to access:
200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 699
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 03 Jan 2022 01:40:01 GMT
Expires: -1
{
"id": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6",
"crossRefId": 479503,
"links": {
"self": {
"href": "https://api.overdrive.com/v1/collections/P1BBQ0AAA23/products/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/availability",
"type": "application/vnd.overdrive.api+json"
}
},
"actions": {
"checkout": {
"href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/",
"type": "application/vnd.overdrive.content.api+json",
"method": "post",
"fields": [
{
"name": "reserveId",
"type": "text",
"value": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6",
"optional": false
},
{
"name": "formatType",
"type": "text",
"value": "",
"options": [
"audiobook-wma",
"audiobook-mp3"
],
"optional": true
}
]
}
},
"collections": [
{
"id": "My Digital Library (OverDrive Training Demo) (OH)",
"copiesOwned": 4,
"copiesAvailable": 3,
"numberOfHolds": 0
},
{
"id": "Your Public Library",
"copiesOwned": 1,
"copiesAvailable": 1,
"numberOfHolds": 0
}
],
"available": true,
"copiesOwned": 5,
"copiesAvailable": 4,
"numberOfHolds": 0
}
For more information on using the search or availability template values, please see the Search and Library Availability API pages.
Updating the patron's lending periods (PUT)
If a user would like a longer or shorter lendingPeriod for each formatType (e.g., ebook or audiobook), you can make individual calls to update their preference.
Sometimes a library might have an override in place that limits the lending period for any given format. If this is the case, you'll get a successful 204 response, but the actual lending period will not change. If the library ever removes the override, the patron's updated preferences will be returned when you send your next GET request to the Patron Information endpoint.
Here's an example PUT request to the /v1/patrons/me endpoint to update the user's ebook lending period.
PUT https://patron.api.overdrive.com/v1/patrons/me
User-Agent: {Your application}
Content-Type: application/json
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Content-Length: 222
{
"fields": [
{
"name": "formatClass",
"value": "ebook"
},
{
"name": "lendingPeriodDays",
"value": "7"
}
]
}
When the update is successful, you'll get a response like this:
HTTP/1.1 204 OK Cache-Control: no-cache Pragma: no-cache Content-Type: application/json; charset=utf-8 Expires: -1 X-Frame-Options: deny Date: Fri, 10 Jul 2015 19:30:45 GMT Content-Length: 1579
