LibKey Lending Tool API Documentation

Below outlines the various calls and elements produced by the LibKey Lending Tool’s API (INCDocs is the branded version of this service used by NHS England and for whom this documentation is also applicable).

Authenticating to the API

You will need a Third Iron API Key that is specially scoped to using the lending tool. Please email us at support@thirdiron.com to request your API key, and mention which group you are with so we can get you the correct access.

Once you have your API key, use it as a Bearer Token on a header, or in a query parameter of access_token at the end of a URL, as shown in the examples below.

Get a list of libraries

Supported Methods	GET
Endpoint Location	/public/v1/libraryGroups/:library_group_id/libraries?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff
Endpoint Parameters
:library_group_id	Replace the :library_group_id portion of the endpoint path with the id # of your library group, which will be provided by support@thirdiron.com

Library List Response

The LibKey Library List response is a JSON object if the library group ID is found in the LibKey system. The structure of the response overall is described in the following tables.

Response Object

Property

Type

Description

data

Array

An array of Library Result objects is returned if the Fulfillment Request ID and Library Group ID is recognized.

Library Result

A Library Result represents a single library in the associated LibKey library group.

The full list of properties that may appear on a Library Result are described in detail in the table below:

Property	Type	Description	Optional
id	string	A unique ID for the library ID.	No
type	string	The value `libraries`	No
name	string	The human-readable name of the library.	No

Example response body

{
  "data": [
    {
      "id": "39411",
      "name": "First Library in the Group",
      "type": "libraries"
    },
    {
      "id": "39412",
      "name": "Second Library in the Group",
      "type": "libraries"
    }
  ]
}

Check the availability of an article in a library group

Supported Methods	GET
Endpoint Location	/public/v1/libraryGroups/:library_group_id/libraries/:library_id/articles/doi/:article_doi?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff -or- /public/v1/libraryGroups/:library_group_id/libraries/:library_id/articles/pmid/:article_pmid?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff
Endpoint Parameters
:library_group_id	Replace the :library_group_id portion of the endpoint path with the id # of your library group
:library_id	Replace the :library_id portion of the endpoint path with the id # of your library
:article_doi	Replace :article_doi with the DOI of an article. Only one DOI can be supplied. (DOI value does not need to be URI encoded)
:article_pmid	Replace :article_pmid with the pmid of an article. Only one pmid can be supplied.
Optional Includes
?include=journal	Adding this include to your request will cause the response to include information about the journal that the DOI is located within. This includes the name of the journal, ISSN, SJR Value, Cover Image URL, BrowZine Enabled Status and the Link to the Journal (more details below including example response)

Availability of an article in a library group response

If the article is recognized by Third Iron systems, many details about the article will be returned. See https://thirdiron.atlassian.net/wiki/spaces/BrowZineAPIDocs/pages/edit-v2/65699928#LibKey-Article-DOI-or-PMID-Lookup-Response%3A for the article-specific details.

There are a small number of fulfillment request-specific fields in the response that you can use to craft a fulfillment request:

Property	Type	Description	Optional
illLibraryId	string	If an article is available at another library, this property will exist with an ID as its value.	Yes
illLibraryName	string	If an article is available at another library, this displays the human-readable name of the library.	Yes

Example response body

{
    "data": {
        "id": 76582654,
        "type": "articles",
        "title": "Assessment of Stable Coronary Lesions",
        "date": "2017-05-11",
        "authors": "Bhatt, Deepak L.",
        "inPress": false,
		"doi": "10.1056/NEJMe1702728",
		"pmid: "28317425",
		"openAccess": false,
        "fullTextFile": "https://libkey.io/libraries/73/articles/143256905/full-text-file",
		"contentLocation": "https://libkey.io/libraries/73/articles/143256905",
        "availableThroughBrowzine": true,
        "startPage": "1879",
        "endPage": "1881",
        "browzineWebLink": "https://browzine.com/libraries/73/journals/10292/issues/36167007?showArticleInContext=doi:10.1056/NEJMe1702728",
        "illLibraryId": "123",
        "illLibraryName": "Library That Has This Article"
    }
}

Create a fulfillment request

Supported Methods	POST
Endpoint Location	/public/v1/libraryGroups/:library_group_id/fulfillmentRequests?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff
Endpoint Parameters
:library_group_id	Replace the :library_group_id portion of the endpoint path with the id # of your library group
Mandatory Body Fields	These must appear in the body of the POST
type	This should be the value `fulfillment-requests`
articleId	Send the DOI of an article. Only one DOI can be supplied. DOI value does not need to be URI encoded.
requesterLibraryId	This is the Third Iron ID of your library, to indicate from where the fulfillment request is arriving.
requesterEmail	This is the email address to which you would like the fulfillment response to arrive.
lenderLibraryId	This is the library ID from which you would like to attempt to borrow the article. This typically should be captured by using the “Check the availability of an article in a library group” endpoint documented above.
Optional Body Fields
customReference	Add a string here if you would like to store a unique identifier for your fulfillment request.

Create fulfillment request response

Details about the fulfillment request will be returned if the POST is successful. See https://thirdiron.atlassian.net/wiki/spaces/BrowZineAPIDocs/pages/edit-v2/3445522433#Fulfillment-Request-Result%3A for details about what is in that request.

If a problem occurs, a 4xx or 5xx HTTP status code will be returned informing you if your API token is not working, you have been rate limited, a temporary problem happened on Third Iron’s servers, etc.

Get the status of a fulfillment request

Supported Methods	GET
Endpoint Location	/public/v1/libraryGroups/:library_group_id/fulfillmentRequests/:fulfillment_request_id?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff
Endpoint Parameters
:library_group_id	Replace the :library_group_id portion of the endpoint path with the id # of your library group
:fulfillment_request_id	Replace the :fulfillment_request_id portion of the endpoint path with the ID # of your fulfillment request. This is typically acquired when you create a fulfillment request using the POST endpoint documented above.
Optional Includes
?include=journal	Adding this include to your request will cause the response to include information about the journal that the DOI is located within. This includes the name of the journal, ISSN, SJR Value, Cover Image URL, BrowZine Enabled Status and the Link to the Journal (more details below including example response)

Fulfillment Request Status Response

The LibKey Fulfillment Request Status is a JSON object if the fulfillment request is found in the LibKey system. The structure of the response overall is described in the following tables.

Response Object

Property

Type

Description

data

Object

A Fulfillment Request Result object is returned if the Fulfillment Request ID and Library Group ID is recognized.

Fulfillment Request Result

A Fulfillment Request Result represents a fulfillment request that the LibKey system is aware of.

The full list of properties that may appear on a Fulfillment Request result are described in detail in the table below:

Property	Type	Description	Optional
id	string	The article's unique id in the Third Iron system. It follows a format of YYYYMMDD-{unique_id}	No
type	string	The value `fulfillment-requests`	No
created	date & time	When the fulfillment request was created.	No
lastUpdated	date & time	When the fulfillment request was last updated, such as when its “status” was last changed.	No
status	string	One of the following values: `pending` - the lender library has not determined whether they can complete the lending or will decline it `complete` - the lender library has contacted the requester email with the article `declined` - the lender library declined lending the article. See the `declinedReason` property for more information about why.	No
articleId	integer	A Third Iron article ID (not a DOI) that helps Third Iron keep track of which article was requested in the system.	No
requesterLibraryId	integer	The ID of the library that is requesting the article.	No
requesterEmail	URL	The email address of the person / entity requesting the article.	No
lenderLibraryId	integer	The ID of the library that has been requested to lend the article.	No
libraryGroupId	integer	The ID of the library group to which the library belongs.	No
declinedReason	string	A value entered by the lender library informing the requester why the article was unable to be lent.	No
customReference	string	If the requester library added a custom reference value, it is stored and displayed here.	Yes

Example response body

{
  "data": {
    "id": "20221003-randomid",
    "type": "fulfillment-requests",
    "created": "2024-10-21T23:58:11.833Z",
    "lastUpdated": "2024-10-21T23:58:11.833Z",
    "status": "pending",
    "articleId": 689611,
    "requesterLibraryId": 9875,
    "requesterEmail": "requester@foo.somewhere",
    "lenderLibraryId": 9876,
    "libraryGroupId": 123,
    "customReference": "abc-123",
    "relationships": {
      "article": {
        "data": {
          "id": 689611,
          "type": "articles"
        }
      },
      "journal": {
        "data": {
          "type": "journals"
        }
      },
      "issue": {
        "data": {
          "id": 68961,
          "type": "issues"
        }
      },
      "requesterLibrary": {
        "data": {
          "id": 9875,
          "type": "libraries"
        }
      },
      "lenderLibrary": {
        "data": {
          "id": 9876,
          "type": "libraries"
        }
      }
    }
  }
}