Download API v2

The Download API allows you to GET a contentLink, which requests a title from our (or our outside provider's) fulfillment servers. Each format, like magazine-overdrive or ebook-adobe, has a contentLink that works a little differently.

Most API implementations use the downloadRedirect endpoint instead, which directs users to a page where they can download their borrowed titles. If your implementation uses our downloadRedirect, you won't be able to use the Download API. However, if your implementation has been granted access to the download API for direct fulfillment, you can use this documentation.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com. For more information on the integration environment, please see Getting Started.

If you're using the download API v1 in your product, you can find the original documentation here. We'll continue to support the prior query parameters, but recommend that you switch to the most current version when possible.

Using the Checkouts API with download links

When you check out a title from the Checkouts API, you’ll get a downloadLink in the linkTemplates section that you can use to get the contentLink to download the title.

Learn more about using the Checkouts API with download links here.

Getting a contentLink to download a title

Make a GET request to the downloadLink endpoint with the desired title's reserve ID. The call to this endpoint must be made dynamically after a user clicks the download button from your website or app because of the contentLink 60-second timeout and single-use restrictions. If your website or app renders the contentLink as a direct, clickable link, it's likely that the link will expire by the time a user actually clicks on it.

Note: If a contentLink isn't fulfilled within the 60-second time limit, a new request must be made for a fresh contentLink.

Send a GET request to the downloadLink endpoint, using the provided linkTemplate from the Checkouts API response for the title you're trying to download. Here's an example of how it'll look:

https://patron.api.overdrive.com/v2/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl={errorurl}

Note: At an OverDrive website, we automatically filter out formats that aren't compatible with the device that's being used to access the site (based on user agent). This way, users don't see the formats they can't get with the device they're using right then. If you'd like a similar feature in place, it's something you'll have to develop independently into your app or website.

The {errorurl} parameter requires you to supply a base error page URL. In our example GET below, we replaced the {errorurl} 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 and appended to your supplied error page URL using the following query string parameters:

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.
reserveId: OverDrive streaming titles will return this as well to identify which title encountered the error.
read_error: An error code specific to OverDrive Read and OverDrive Listen.

Note: All query string parameters you add to the downloadLink template must be URL encoded.

To GET a contentLink, the format you're requesting must be locked in (unless it's a format that's always available, like ebook-overdrive or audiobook-overdrive). Below, you'll find a sample downloadLink GET request with a completed downloadLink template.

GET https://patron.api.overdrive.com/v2/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/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

A successful response provides the contentLink:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 546
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Fri, 27 Sep 2013 13:52:22 GMT
Expires: -1

{
    "reserveId": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6",
    "formatType": "audiobook-mp3",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm",
            "type": "application/vnd.overdrive.content.api+json"
        },
        "contentLink": {
            "href": "https://ofs.contentreserve.com/bin/OFSGatewayModule.dll/Dracula.odm?RetailerID=odapilib&Expires=1380293542&Token=9736c5b1-69f7-4d50-809b-308c3a20b0ac&Signature=23HFZzxZqRUi7bAHXb0B0HJrWOY=",
            "type": "application/x-od-media"
        }
    }
}

You can then use the contentLink to download the title. As mentioned earlier, the contentLink for each format works a little differently:

For Adobe EPUBs: the contentLink delivers an ACSM file that opens in Adobe Digital Editions or OverDrive's mobile app.
For OverDrive Read, OverDrive Listen, MediaDo Reader, and magazines: the contentLink opens the title in its in-browser reader or player.
For MP3 audiobooks: the contentLink delivers an ODM file that opens in OverDrive's desktop app (for Windows or Mac) or OverDrive's mobile app.