Page Comparison

...

Table of Contents

style	none

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.

...

Supported Methods	GET
Endpoint Location	`https://public-api.thirdiron.com/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

language	json

{
  "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	`https://public-api.thirdiron.com/public/v1/libraryGroups/:library_group_id/libraries/:library_id/articles/doi/:article_doi?access_token=ffffffff-ffff-ffff-ffff-ffffffffffff` -or- `https://public-api.thirdiron.com/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, 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 https://thirdiron.atlassian.net/wiki/spaces/BrowZineAPIDocs/pages/edit-v2/65699928#LibKey-Article-DOI-or-PMID-Lookup-Response%3A for the article-specific details.

...

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

Code Block

language	json

{
    "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	`https://lendingtool-api.thirdiron.com/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 `data` Fields	These must appear in the body of the POST in an element named `data`
type	String - This should be the value `fulfillment-requests`
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

Code Block

language	json

{
    "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 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	`https://public-api.thirdiron.com/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	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.

...

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 `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.	Yes
customReference	string	If the requester library added a custom reference value, it is stored and displayed here.	Yes

Example Response Body

Code Block

language	json

{
    "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"
          }
        }
      }
    }
  }

Versions Compared

Old Version 4

New Version Current

Key

Authenticating to the API

Library List Response

Response Object

Library Result

Example response body

Check the availability of an article in a library group

Availability of an article in a library group response

Example response body

Create a fulfillment request

Example fulfillment request body

Create fulfillment request response

Get the status of a fulfillment request

Fulfillment Request Status Response

Response Object

Fulfillment Request Result

Example Response Body