Patrons

What do the Patrons Endpoints do?

The Patrons Endpoints allows a patron to interact with a library catalog—specifically titles.

These 7 endpoints can be called to borrow a Hoopla title (1), place a hold on a Hoopla title (2), return a Hoopla title early (3), remove their hold from a Hoopla title (4), see a list of all content they currently have borrowed on Hoopla (5), see a list of all titles they currently have on hold through Hoopla and where they are in the holds queue (6), and see how many Instant Hoopla borrows they have remaining for the month (7), which is helpful to see after a new borrow has been completed through the library catalog. The last endpoint (7) also shows how many total Hoopla borrows they are allowed each month, and how many Hoopla titles they have currently borrowed.

We’ll break out each of the 7 endpoints in more detail below.

Using the Patrons Endpoint – Borrow a Title

A use case for calling the patrons borrow endpoint would be to allow the user to borrow a Hoopla title while also seeing when said title would be due back to the library. This gives the patron an idea of how long they have to read an ebook or watch a movie, for example, which contributes to their decision to borrow. The borrowed and due response values are unix time.

Patrons Endpoint Documentation – Borrow a Title

POST: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/{contentId}

Response Class (Status 200)

Model Schema

{ 
  "contentId": 0, 
  "title": "string", 
  "borrowed": 1466585147, 
  "due": 1466585147, 
  "kind": "string", 
  "url": "string", 
  "coverImageUrl": "string", 
  "message": "string" 
} 

Response Messages

Example Requests and Responses – Borrow a Title

Example Request

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/13280634' 

Example Response

{ 
  "contentId": 13280634, 
  "title": "Harry Potter and the Sorcerer's Stone", 
  "borrowed": 1744039135, 
  "due": 1745853535, 
  "kind": "EBOOK", 
  "url": "https://www.hoopladigital.com/title/13280634", 
  "message": "You can now enjoy this title through Monday, April 28.  You can stream it to your browser, or download it for offline viewing using our Amazon, Android, or iOS mobile apps." 
} 

Using the Patrons Endpoint – Place a Hold

A use case for calling the patrons place a hold endpoint would be to allow the user to add a patron hold to a Hoopla flex title. 

Patrons Endpoint Documentation – Place a Hold

POST: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/holds/{contentId}

Response Class (Status 200)

Model Schema

{ 
  "status": "string", 
  "contentId": 0, 
  "title": "string", 
  "inserted": 1466585147, 
  "reserveUntil": 1466585147, 
  "url": "string", 
  "coverImageUrl": "string", 
  "kind": "string", 
  "holdsQueuePosition": 0 
} 

Response Messages

Example Requests and Responses – Place a Hold

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/13966741

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/13966741' 

Example Response

{ 
  "status": "WAITING", 
  "contentId": 13966741, 
  "title": "The Four Winds", 
  "inserted": 1744039918, 
  "url": "https://www.hoopladigital.com/title/13966741", 
  "coverImageUrl": "https://cover.hoopladigital.com/mcm_9781250178626_270.jpeg", 
  "kind": "EBOOK", 
  "holdsQueuePosition": 2 
} 

Using the Patrons Endpoint – Return a Title Early

A use case for calling the patrons return a title (early) endpoint would be to allow the user to return a title before the due date once they’ve decided they’re finished with the title.

Patrons Endpoint Documentation – Return a Title Early 

DELETE: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/{contentId}

Response Messages

Example Requests and Responses – Return a Title Early

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/13280634 

curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/13280634' 

Example Response

no content

Using the Patrons Endpoint – Remove a Hold on a Title

A use case for calling the patrons remove a hold on a title endpoint would be to allow the user to delete their hold on a title, therefore potentially releasing the title to other waiting patrons.

Patrons Endpoint Documentation – Remove a Hold on a Title

DELETE: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/holds/{contentId}

Response Messages

Example Requests and Responses – Remove a Hold

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/13966741

curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/13966741'

Example Response

no content

Using the Patrons Endpoint – View Currently Borrowed Titles

A use case for calling the patrons view currently borrowed titles endpoint would be to allow the patron to see a list of all content they currently have borrowed on Hoopla.

Patrons Endpoint Documentation – View Currently Borrowed Titles

GET: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/checkouts/current

Response Class (Status 200)

Model Schema

[ 
  { 
    "contentId": 0, 
    "title": "string", 
    "borrowed": 1466585147, 
    "due": 1466585147, 
    "kind": "string", 
    "url": "string", 
    "coverImageUrl": "string", 
    "message": "string" 
  } 

Response Messages

Example Requests and Responses – View Currently Borrowed Titles

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/checkouts/current

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/checkouts/current'

Example Response

{ 
  "contentId": 13280634, 
  "title": "Harry Potter and the Sorcerer's Stone", 
  "borrowed": 1744039135, 
  "due": 1745853535, 
  "kind": "Ebooks", 
  "url": "https://www.hoopladigital.com/title/13280634", 
  "coverImageUrl": "https://cover.hoopladigital.com/csp_9781781100486_270.jpeg" 
}

Using the Patrons Endpoint – List of Holds and Position in Queue

A use case for calling this patrons endpoint would be to view a list of all titles they currently have on hold through Hoopla, and where they are in the holds queue.

Patrons Endpoint Documentation – List of Holds and Position in Queue

GET: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/holds/current

Response Class (Status 200)

Model Schema

{ 
    "status": "string", 
    "contentId": 0, 
    "title": "string", 
    "inserted": 1466585147, 
    "reserveUntil": 1466585147, 
    "url": "string", 
    "coverImageUrl": "string", 
    "kind": "string", 
    "holdsQueuePosition": 0
 } 

Response Messages

Example Requests and Responses – List of Holds and Patrons in Queue

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/current

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/holds/current'

Example Response

{ 
  "status": "WAITING", 
  "contentId": 13966741, 
  "title": "The Four Winds", 
  "inserted": 1744039918, 
  "url": "https://www.hoopladigital.com/title/13966741", 
  "coverImageUrl": "https://cover.hoopladigital.com/mcm_9781250178626_270.jpeg", 
  "kind": "EBOOK", 
  "holdsQueuePosition": 2 
}

Using the Patrons Endpoint – Number of Current Borrows and Remaining Borrows for the Month

A use case for calling this patrons endpoint would be to view how many instant borrows they have remaining for the month, which is helpful to see after a new borrow has been completed through the library catalog. This also shows how many total borrows they are allowed each month, and how many titles they have currently borrowed.

Patrons Endpoint Documentation – Number of Current Borrows and Remaining Borrows for the Month

GET: /api/v1/libraries/{libraryId}/patrons/{libraryCard}/status

Response Class (Status 200)

Model Schema

{ 
  "borrowsRemaining": 0, 
  "borrowsAllowedPerMonth": 0, 
  "currentlyBorrowed": 0 
} 

Response Messages

Example Requests and Responses – Number of Current Borrows and Remaining Borrows for the Month

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/status

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 8b3848d1-a70c-4ac9-b63d-432d412f4d85' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/patrons/5000604155/status'

Example Response

{ 
  "borrowsRemaining": 10, 
  "borrowsAllowedPerMonth": 10, 
  "currentlyBorrowed": 5 
}