Download API (v1, old query parameters)

Download API v1 is a legacy API that's no longer receiving updates or improvements.

Most API implementations now use the downloadRedirect endpoint of the Checkouts API instead of the Download API. Visit the Checkouts API to learn more about the downloadRedirect endpoint.

If your implementation has been granted access to the Download API for direct fulfillment, you can use this documentation. If you need documentation for v2 of the Download API, you can find it here.

The legacy Download API allows you to GET a contentLink. This link requests a title download from our fulfillment servers. For OverDrive Read and Listen titles, the contentLink will open the title directly in the user's browser. In the case of Adobe EPUBs, the contentLink delivers an ACSM file that opens in Adobe Digital Editions.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com.

The OverDrive Download API doesn't filter formats by detecting an end user's device. If you'd like to add format filtering, you'll need to do so within the app you're developing.

Using the Download API

Make a GET request to the downloadLink endpoint with the title's reserve ID. You can find the downloadLink template in the Checkouts API response (in the linkTemplates section).

Resource URL

https://patron.api.overdrive.com/v1/patrons/me/checkouts/{reserve ID}/formats/{format}/downloadlink?errorpageurl={errorpageurl}

The {errorpageurl} parameter requires you to supply a base error page URL. In our example GET below, we replaced the {errorpageurl} value with https://www.yourwebpage.com/errorpage.htm. If there is a fulfillment error when processing your GET request, the error code will be returned appended to your supplied error page URL using the following query string parameters:

Parameter	Description
ErrorCode	An OverDrive-specific error code
ErrorDescription	A basic description of the error
ErrorDetails	A more detailed description of the error. You may want to consider logging this information rather than displaying it to end users.

Note: All query string parameters must be URL encoded.

To GET a contentLink, the format you're requesting must be locked in.

Example request

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-epub-adobe/downloadlink?errorurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Connection: Keep-Alive

Example response

200 OK
Date: Thu, 29 Aug 2024 20:56:25 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 629
Content-Type: application/json; charset=utf-8
                     
{
    "reserveId": "864604e2-0146-46ef-a96d-d9977dc15263",
    "crossRefId": 686192,
    "formatType": "ebook-epub-adobe",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-epub-adobe/downloadlink?errorUrl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "contentlink": {
            "href": "https://fulfill.contentreserve.com/GoneGirl_9780307588388_686192.acsm?RetailerID={id}&amp;Expires=1724968563&amp;Token=cdc322dd-e949-4f26-85c6-b1db011711f5&amp;Signature=ibQNWRczs8RlYtoIYTT%2fsUr3t9I%3d",
            "type": "application/vnd.adobe.adept+xml"
        }
    }
}

You can use the contentLink to download the title. For ACSM files, fulfillment is not complete until the file has been opened.

Note: contentLinks are one time use and are only valid for 60 seconds. If fulfillment is not completed within that timeframe, you'll need to request a new contentLink.

Getting a contentLink for an OverDrive Read ebook or an OverDrive Listen audiobook

Since the OverDrive app is no longer widely available, we recommend fulfilling titles with the OverDrive Read or Listen format. These formats open directly in the user's browser and don't require additional software.

When requesting an OverDrive Read ebook or an OverDrive Listen audiobook contentLink, you'll need to provide an authorization page URL (odreadauthurl) in addition to the reserve ID, format, and errorpageurl.

https://patron.api.overdrive.com/v1/patrons/me/checkouts/{reserve ID}/formats/{format}/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}

In the example GET below, we replaced {odreadauthurl} with https://www.yourwebpage.com/odreadauth?reserveid=[RESERVE_ID]&read_error=[READ_ERROR].

Example request

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-overdrive/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&amp;odreadauthurl=https%3a%2f%2fwww.yourwebpage.com%2fodreadauth%3Freserveid%3D%5BRESERVE_ID%5D%26read_error%3D%5BREAD_ERROR%5D
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Connection: Keep-Alive

Example response

200 OK
Date: Thu, 29 Aug 2024 20:56:25 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 629
Content-Type: application/json; charset=utf-8          

{
    "reserveId": "864604e2-0146-46ef-a96d-d9977dc15263",
    "crossRefId": 686192,
    "formatType": "ebook-overdrive",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-overdrive/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&amp;odreadauthurl=https%3a%2f%2fwww.yourwebpage.com%2fodreadauth%3Freserveid%3D%5BRESERVE_ID%5D%26read_error%3D%5BREAD_ERROR%5D",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "contentlink": {
            "href": "https://fulfill.contentreserve.com/GoneGirl_9780307588388_686192.epub-sample.overdrive.com?RetailerID=odapilib&amp;Expires=1724968585&amp;Token=06d0e17f-0b41-4836-bd4f-b1db01172b41&amp;Signature=yvuoiv4d1EW%2fmJeT6E6PCDaOl9M%3d",
            "type": "text/html"
        }
    }
}

The contentLink for an OverDrive Read ebook or an OverDrive Listen audiobook is a direct link to open the title in the user's web browser.

There are a series of error codes associated specifically with OverDrive Read and OverDrive Listen fulfillment. Possible errors:

D001: missing
No message was supplied in the request.
D002: stale
The contentLink used was more than 60 seconds old when Read or Listen tried to open it.
D003: expired
The lending period has expired for the requested ebook or audiobook.
D004: message reused
The contentLink was already used to access the ebook or audiobook.
D101: message signature mismatch
The "signature" doesn't match the message. This can indicate a failed attempt to forge the message.
D102: message unreadable
The attempt to load the object via JSON and base64 failed, or required properties were missing.
D103: theme unavailable
The message specifies a theme, but the theme is not in the connector's list of available themes.
D104: book not found
No ebook or audiobook was found that matches the reserveId in the given domain name.
D105: book not in your catalogs
An ebook or audiobook matching the reserveId was found, but not in any of the catalogs the connector has access to.
D106: book not compatible with outlet
The ebook or audiobook was found, but the wrong outlet (player or reader) tried to open the file (e.g., an ebook tried to open in OverDrive Listen).

When an error is encountered during OverDrive Read or OverDrive Listen fulfillment, the user will be redirected to the {odreadauthurl} value that you supplied with the contentLink request. The particular OverDrive Read error code that occurred will be substituted into the read_error=[READ_ERROR] parameter of the response.