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).
| Table of Contents | ||
|---|---|---|
|
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
...
| Code Block |
|---|
GET |
...
Endpoint Location
...
| Code Block |
|---|
/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
| Code Block |
|---|
{
"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
...
| Code Block |
|---|
GET |
...
Endpoint Location
...
| Code Block |
|---|
/public/v1/libraryGroups/:library_group_id/libraries/:library_id/articles/doi/:article_doi?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff |
-or-
| Code Block |
|---|
/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
| Code Block |
|---|
{
"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
...
| Code Block |
|---|
POST |
...
Endpoint Location
...
| Code Block |
|---|
/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
...
| Code Block |
|---|
GET |
...
Endpoint Location
...
| Code Block |
|---|
/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 itcomplete- the lender library has contacted the requester email with the articledeclined- the lender library declined lending the article. See thedeclinedReasonproperty 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
...
Please see the updated documentation here: LibKey Lending Tool API Documentation New