Library Entitlements

What does the Library Entitlements Endpoint do?

The Library Entitlements Endpoint retrieves library-specific content entitlements. You can filter by status to return active items (content the library makes available to patrons), inactive (content the library has decided to not make available), or all. You can call for a delta, which would allow for specificity around newly added or removed titles. You can also limit by purchase model to return either Instant (pay-per-use) items, Flex (one-copy-one-user) items, or all items.

This endpoint is used in tandem with the Global Contents endpoint, which provides the title-specific metadata, and will allow a partner to call the Hoopla Partner API for only the content they need rather than calling the API daily for millions of titles.

Using the Library Entitlements Endpoint

When a library decides to turn on their Hoopla API catalog integration, they will likely run a full title ingestion and then appropriately scope their catalog based on what they own. The Global Content endpoint provides access to all available Hoopla records and metadata. The Library Entitlements endpoint allows the library to identify which of these records should appear in their library catalog.

Library Entitlements Endpoint Documentation

GET: /api/v1/libraries/{libraryID}/entitlements

Response Class: (Status 200)

Model Schema

{ 
  "metadata": { 
    "totalCount": 1073741824, 
    "nextStartToken": "string", 
    "warnings": [ 
      "string" 
    ] 
  }, 
  "data": { 
    "additionalProp1": [ 
      { 
        "contentId": 9007199254740991, 
        "active": true 
      } 
    ], 
    "additionalProp2": [ 
      { 
        "contentId": 9007199254740991, 
        "active": true 
      } 
    ], 
    "additionalProp3": [ 
      { 
        "contentId": 9007199254740991, 
        "active": true 
      } 
    ] 
  } 
} 

Response Messages

Considerations for using the Library Entitlements Endpoint

The Library Entitlements endpoint is best used in tandem with the Global Contents endpoint. The partner can call the Hoopla Partner API the content they need, specifying the library, calling for additions and/or removals since the last time they used this specific endpoint (calling for a delta), filtering by a purchase model, etc. The main focus of the Library Entitlements endpoint is allowing the partner see what a library does or does not own. 

The only required field in this endpoint request is libraryId. 

Response Key Attributes

• contentId: Unique content identifier
• active: true or false, depending on whether or not the title is visible to patrons

Requests and Responses

Example Request

https://hoopla-api.hoopladigital.com/api/v1/libraries/7/entitlements?limit=5   
curl -X 'GET' \ 
  'https://hoopla-api.hoopladigital.com/api/v1/libraries/7/entitlements?limit=5' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer 86b62419-762b-4b21-8c29-2331873a8169' 

Example Response

{ 
  "metadata": { 
    "totalCount": 5, 
    "nextStartToken": "10023346" 
  }, 
  "entitlements": [ 
    { 
      "contentId": 10023289, 
      "active": false 
    }, 
    { 
      "contentId": 10023298, 
      "active": false 
    }, 
    { 
      "contentId": 10023299, 
      "active": false 
    }, 
    { 
      "contentId": 10023300, 
      "active": true 
    }, 
    { 
      "contentId": 10023346, 
      "active": false 
    } 
  ] 
}