Skip to Content
IntegratorsResponse

Response

For each DOI in the request, an Entitlement object is included in the response, which establishes the level of entitlement, access type, document type (version of record or alternative version), content type and a smart link (WAYFless URL) to the actual resource if appropriate.

{
  "entitlements": [
    {
      "doi": "10.10/does.not-exist",
      "statusCode": 404
    },
    {
      "doi": "10.10/1234",
      "statusCode": 200,
      "entitled": "yes",
      "accessType": "paid",
      "source": "service_request",
      "document": "https://link-to-content-on-publisher-platform.com",
      "org": {
        "ipv4": "1.2.3.4"
      },
      "vor": [
        {
          "contentType": "application/pdf",
          "url": "https://link-to-content-on-pubisher-platform.com"
        }
      ],
      "av": [],
      "updates": [],
      "licenses": [
        {
          "type": "cc_by",
          "url": "https://creativecommons.org/licenses/by/4.0/"
          "startDate": "2022-01-04"
        }
      ]
    },
    {
      "uid": "b2d8bfea-050e-4293-af31-725815a1fa8b",
      "doi": "10.10/5678",
      "statusCode": 200,
      "entitled": "no",
      "accessType": "paid",
      "source": "service_request",
      "document": "https://link-to-content-on-publisher-platform.com",
      "av": [],
      "updates": [],
      "licenses": []
    }
  ]
}

Entitlement Object

PropertyDescription
"doi"The document identifier
"statusCode"A “HTTP Status code” like field, that reflects the entitlement response type
"entitled"Possible values: "yes", "no", "maybe"
"accessType"Possible values: "open", "free", "permFree", "paid"
"org"In the response, the “org” object contains the actual org ID(s) used to establish entitlement. If present, the org is known and was used to establish the level of entitlement.
"vor"Version of Record object contains an array of Documents (see below)
"av"Alternate Version object contains an array of Documents (see below)
"document"The URL for the document’s landing page.
"source"The origin of the entitlement within our service, this can be used for debugging purposes. Possible values are: "unknown", "pubisher_not_supported", "oa_platform", "service_cache", "centralised", "service_request"
"updates"Contains the updates to the current doi (if any). It is an array of Update Objects (see below)
"licenses"Contains the licenses associated to the current doi (if any). It is an array of License Objects (see below)
"uid"The unique identifier is returned when it was present in the DOI object of the request. This can be used to map the entitlements in the response to the queried documents in the request when the DOI was not known at request time.
ℹ️

The "updates" and "licenses" fields are optional features that can be enabled for integrators. If you are interested in these features, please get in touch.

⚠

GetFTR does not deduplicate the updates from different sources, so the “updates” > array can hold multiple records with the same updateDate, updateType and updateDoi. > Also, the order of the records is not defined, so never use the first or latest > update item to gain information about the latest update of a document.

Source Field

The source field inside the entitlement response object is primarily used for debugging and investigatory purposes. It indicates the source of the entitlement response on the GetFTR platform.

ValueDescription
unknownRepresents an unknown source. Such that we were unable to retrieve the DOI (ie. it does not exist).
publisher_not_supportedThe DOI belongs to a publisher we don’t currently support.
oa_platformThe entitlement information was retrieved from the GetFTR OA & Free service.
service_cacheThe entitlement information was retrieved from the Cache.
centralisedThe entitlement was retrieved from the centralised entitlements API, where publishers have shared entitlements with GetFTR.
service_requestThe entitlement information was retrieved by contacting the publisher’s API.

Document Object

In addition to the "document" property in the Entitlement object, the Document object holds additional links to other content types, such as PDF. One or more Document objects can be present in the vor and av arrays.

PropertyDescription
"contentType"The declared MIME type of the document. Possible values:, "application/epub+zip", "text/html", "application/pdf", "other"
"url"A direct URL to the document. Will redirect to an IdP for authentication where appropriate (i.e. a “Smart Link”).

Update Object

This object contains information about any retraction & errata updates for the DOI.

PropertyDescription
"source"The source of the update information. (ie. retractionwatch, crossref)
"updateDoi"The DOI of the document, which holds the updated information about the original document.
"updateDate"Update date (ie. 2000-01-01)
"updateType"The type of the update (ie. retraction, correction, expression-of-concern, reinstatement)
"reasons"An array of strings that contain the detailed reasons for the update (if specified by the source)
"urls"An array of external URLs regarding the update.
ℹ️

GetFTR includes update types from CrossRef, CrossMark AND RetractionWatch

License Object

This object contains information about the licenses of the document.

PropertyDescription
"type"The type of the license. Possible values are: "cc_by", "cc_by_sa", "cc_by_nc", "cc_by_nc_sa", "cc_by_nd", "cc_by_nc_nd", "cc0", "other"
"url"The URL which holds detailed information about the license.
"startDate"Date of when the license became effective in YYYY-MM-DD format.
Last updated on
RequestRedirector