FAQs

What is the quickest path to adoption?

1. Start by making requests without organisation IDs to receive links to HTML and PDF versions of Free, Open Access and Alternative Versions of paid content.
2. Improve your implementation by making requests with an Organisation’s IPv4 or IPv6 address to receive links to paid content the user can access
3. Finally, make requests with an EntityID to receive links to paid content the user can access off-campus or via VPN.

Where to get a list of SAML entityIDs?

https://met.refeds.org  maintains lists of EntityIDs for different institutions.

How to use The Entitlement API?

How the call is made is entirely up to the integrator. We only ask integrators to:

• Follow the Terms & Conditions
• Ensure your API Key does not leak
• Inform us ahead of any period of increased traffic

What happens if multiple institutional identifiers are sent with a single request but only some identifiers are entitled?

It depends on how the publisher has implemented their functionality for dealing with mixed entitlements across multiple identifiers. However, typically if one or more identifiers are entitled, the publisher indicates the user is entitled in the response. The "org" key will typically indicate which identifier was entitled to the content.

Once the user browses to the publisher’s website, it will depend upon the Publisher’s implementation to determine which identifier to authenticate against.

Can GetFTR supply test IDs and DOIs?

GetFTR does not determine entitlement and has no control of access to content on publisher platforms, so is unable to supply test credentials. Use Open Access or Free DOIs for testing. To test Paid content please use your own institution credentials or VPN.

Can multiple organisation IDs be sent at once?

To make the best use of the The Entitlement API send as many IDs as are available. The API will check all IDs and return the best possible entitlement.

Which Identity Providers does The Entitlement API support?

Entitlements are determined by publisher platforms and as such the support depends on the publisher. If an entityID and DOI combination does not result in expected entitlements, reach out to the publisher that owns the content to clarify.

Which organisation IDs does The Entitlement API support?

The Entitlement API accepts a number of organisation IDs defined in The Entitlement API Specification. Publishers will use IDs they support to determine entitlement.

Why is The Entitlement API responding with 401?

It occurs when the API Key included in the request are not valid.

Why is The Entitlement API responding with 429?

It occurs when a set of integrator credentials exceed the request rate limit. Request a rate limit increase by contacting support@getfulltextreasearch.com.

Why is The Entitlement API responding with 5xx for individual DOIs in a batch?

The Entitlement API uses publisher platforms to check entitlements. Occasionally underlying platforms experience issues that are resolved as soon as possible. Check the Dashboard in your portal to see if any of the platforms are experiencing significant disruption. If errors cannot be correlated with publisher status codes, contact support@getfulltextreasearch.com quoting a X-REQUEST-ID.

Can The Entitlement API be accessed in a test environment?

GetFTR does not provide access to non-production environments, please use production credentials for development and testing.

Where is The Entitlement API hosted?

We maintaing servers on AWS in Ireland (eu-west-1) & California (us-west-1).

Can The Entitlement API be called from the browser?

The Entitlement API does not return CORS headers and is not intended to be called from the browser. It is intended to be called from a server-side application.

Why are entitlements for recently registered content not found?

There is a ~24h delay before entitlements for recently registered DOIs become available.

What are the different access types and their definitions?

We currently respond with a number of different access types depending on the content that has been requested:

• free is temporarily free. This is an article that usually requires a paid subscription, but the publisher has made it freely available for a period of time. For example, this might be an article about COVID-19.
• open is Open Access and is always free.
• permFree means permanently free.
• paid indicates this content requires a subscription to access. Our entitlement response should indicate if the user can view this article or not.

What is an Alternative Version?

Alternative Versions are versions of full articles, pre-prints, author-accepted manuscripts and the like that are available to users not entitled to access paid content. The decision on whether or not to provide Alternative Versions of content is solely at each participating publisher’s discretion.

Does The Entitlement API cache entitlements?

Yes, entitlements are cached for performance reasons.

Does The Entitlement API support batching?

Yes.

What usability guidelines and UI assets are available?

Usability guidelines and assets are available at https://www.getfulltextresearch.com/for-integrators/usability-guidelines .