/
Public Lookup API

Public Lookup API

Owned by Owen Stephens
Last updated: Jun 03, 2025

In order to make it possible to display license terms to users in public facing systems (e.g. a discovery system) a publicly accessible API endpoint is available for the Agreements application which returns information on publicly viewable license terms for a particular resource (based on the agreements the resource belongs to).

This was implemented via ERM-356: Expose license terms over APIClosed

The endpoint and full path is `erm/sas/publicLookup`

The endpoint also supports the parameters: `referenceId` and `resourceId` (which both just effectively prepoulate some filters/matches)

For a eHoldings resource it can be used as follows:

  • /erm/sas/publicLookup?referenceId=18-34-32090  find all agreements with that resource as part of it (i.e. there is either an agreement line for the resource or for the package the resource belongs to)

  • /erm/sas/publicLookup?referenceId=18-34  find all agreements specifically with the package (i.e. only cases where the agreement line is for the package)

For an internal KB resource, the resource ID (UUID) for the Title Instance (TI), Platform Title Instance (PTI) or Package Content Item (PCI) or Package  can be supplied for any of our resources:

  • `/erm/sas/publicLookup?resourceId=7549b408-e2ff-41cb-b412-32de9e82e9eb`

This behaves as follows:

  • If the resourceId represents a TI then it will find all agreements which include this title instance

  • If the resourceId represents a PTI then it will find all agreements which include this platform title instance

  • If the resourceId represents a PCI then it will find all agreements which include this package content item

  • If the resourceId represents a Package then it will only find agreements which include the package directly

Additionally you can further filter the results by aspects of the agreement. You can supply the following (all as encoded url parameters):
`term` = term to search by
`match` = properties of the agreement to match
`filters` = any additional filters
`sort` = properties to sort by
`offset` or `page`
`max` or `perPage`

The `term`, `match`, `filters`, `sort` can only be used on the data stored directly on the agreement. So for example:

/erm/sas/publicLookup?resourceId=7549b408-e2ff-41cb-b412-32de9e82e9eb&filters=endDate%3E%3D2023-06-29 

will only return agreements (and their license terms) which contain the resource identified by 7549b408-e2ff-41cb-b412-32de9e82e9eb and have an endDate on 29th June 2023 or later

Note that when returning the agreements that include a resource, only agreements where the resource is currently an active part of the agreement will be included. Whether a resource is an active part of the agreement depends on:

  • That there is an agreement line linking either directly to the resource, or to a package containing the resource

  • That the agreement line active from date (if set) is in the past and the agreement line active to date (if set) is in the future

  • That, in the case the agreement line links to a package, the PCI for the resource has an access start date (if set) in the past and an access end date (if set) in the future (in the case that the agreement line is directly linked to a PCI the access start and access end dates are ignored)

This is to say - if the resource would appear in the list of current resources in the Agreement → Agreement Line → E-resources covered by this agreement display in the UI, then it is counted as active within the agreement. If it would not appear at all, or would appear in the Future or Dropped lists in the UI, then it is not counted as active within the agreement (i.e. the agreement does not currently offer access to the resource)