LibKey Lending Tool API Documentation
- Karl Becker
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 |
|
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 | 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 |
|
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_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 Article DOI/PMID Lookup Endpoint (LibKey) | LibKey Article DOI or PMID Lookup Response: 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 | integer | 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 |
|
Endpoint Parameters |
|
:library_group_id | Replace the :library_group_id portion of the endpoint path with the id # of your library group |
Mandatory Body | These must appear in the body of the POST in an element named |
type | String - This should be the value |
articleId | Integer - The Third Iron ID of the article. Only one ID can be supplied. |
requesterLibraryId | Integer - This is the Third Iron ID of your library, to indicate from where the fulfillment request is arriving. |
requesterEmail | String - This is the email address to which you would like the fulfillment response to arrive. |
lenderLibraryId | Integer - 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. |
customReference | String - Empty string, or a value if you would like to store a unique identifier for your fulfillment request. |
Example fulfillment request body
{
"data": {
"type": "fulfillment-requests",
"articleId": 2349019438,
"requesterLibraryId": 123,
"requesterEmail": "me@gmail.com",
"lenderLibraryId": 4930123,
"customReference": ""
}
}Create fulfillment request response
Details about the fulfillment request will be returned if the POST is successful. See LibKey Lending Tool API Documentation - Old | Fulfillment Request Result: 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 |
|
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 | Optional |
|---|---|---|---|
data | Object | A Fulfillment Request Result object is returned if the Fulfillment Request ID and Library Group ID is recognized. | No |
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 fulfillment request’s unique id in the Third Iron system. It follows a format of YYYYMMDD-{random_unique_id} | No |
type | string | The value | 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:
| 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. | Yes |
customReference | string | If the requester library added a custom reference value, it is stored and displayed here. | Yes |