Page Comparison

...

Authenticating to the API

Details to come about authenticating - tl;dr we need to use the library group scope token introduced in

Jira Legacy

server	System Jira
serverId	f5b3f062-e9f3-30b0-bc71-64b369a7a196
key	BZ-8002

Get a list of libraries

GET /public/v1/libraryGroups/:libraryGroupId/librariesYou 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 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

Code Block

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

New Version 4

Key

Authenticating to the API

Get a list of libraries

Get a list of libraries

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

Create fulfillment request response

Get the status of a fulfillment request

Fulfillment Request Status Response

Response Object

Fulfillment Request Result

Example response body