OverDrive Developers

Using the Checkouts API with download links

With the Checkouts API, you can get download links for each format a title is available in. You can select a format at the time of checkout or use a POST request to lock in a format later.

Most API implementations use the downloadRedirect endpoint, which directs users to a page where they can fulfill and download their borrowed titles. In this case, you won't get download links from the Checkouts API.

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.

Checking out a title (POST)

You can borrow a title on a patron's behalf by sending a POST request to the checkouts endpoint. This request must include the title's reserveId in the request body (as a name and value pair).

Optional fields: You can also include a formatType during the initial checkout request. See second example below.

Here's an example POST that does not lock in a format:

POST https://patron.api.overdrive.com/v1/patrons/me/checkouts
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Content-Type: application/json; charset=utf-8
Host: patron.api.overdrive.com
Content-Length: 104
Expect: 100-continue

{
    "fields": [
        {
            "name": "reserveId",
            "value": "76C1B7D0-17F4-4C05-8397-C66C17411584"
        }
    ]
}

A successful response looks like this:

201 Created
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 1552
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 23 Sep 2013 14:56:38 GMT
Expires: -1
Location: https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584

{
    "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
    "expires": "10/14/2013 10:56:00 AM",
    "isFormatLockedIn": false,
    "formats": [
        {
            "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
            "formatType": "ebook-overdrive",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
		"downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorurl={errorurl}&successurl={successurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            }
        }
    ],
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584",
            "type": "application/vnd.overdrive.content.api+json"
        },
        "metadata": {
            "href": "https://api.overdrive.com/v1/collections/P1BBQ0AAA23/products/76C1B7D0-17F4-4C05-8397-C66C17411584/metadata",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "actions": {
        "format": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats",
            "type": "application/vnd.overdrive.content.api+json",
            "method": "post",
            "fields": [
                {
                    "name": "reserveId",
                    "value": "76C1B7D0-17F4-4C05-8397-C66C17411584",
                    "optional": false
                },
                {
                    "name": "formatType",
                    "value": "",
                    "options": [
                        "ebook-pdf-adobe",
                        "ebook-epub-adobe",
                        "ebook-kindle"
                    ],
                    "optional": false
                }
            ]
        },
        "earlyReturn": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584",
            "method": "delete"
        }
    }
}

In the format action, you'll find the available formatType options for the title. To lock in an available format (ebook-pdf-adobe, ebook-epub-adobe, or ebook-kindle), make a POST request to the formats endpoint. Here's an example of a POST request to the formats endpoint.

Only one format can be locked in per title. The OverDrive Read and Listen formats don't need to be locked in and persist as reading/listening options even after you lock in another format. This means a user can typically access an ebook or audiobook in two ways: via OverDrive Read or Listen and via the format that's locked in (e.g., Kindle Book or MP3 audiobook).

Note: Not all titles are available in the OverDrive Read or Listen format.

If you want to lock in a format during the initial checkout request, you'll need to include an available formatType in the POST request (a second name and value pair). Here's an example POST request that locks in a format:

POST https://patron.api.overdrive.com/v1/patrons/me/checkouts
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Content-Type: application/json; charset=utf-8
Host: patron.api.overdrive.com
Content-Length: 171
Expect: 100-continue

{
    "fields": [
        {
            "name": "reserveId",
            "value": "76C1B7D0-17F4-4C05-8397-C66C17411584"
        },
        {
            "name": "formatType",
            "value": "ebook-epub-adobe"
        }
    ]
}

As long as the checkout is successful, you'll get a 201 response back:

201 Created
Cache-Control: no-cache
Pragma: no-cache
Location: https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C
X-Frame-Options: deny
Date: Thu, 07 Feb 2019 15:18:43 GMT
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 2666

{
    "reserveId": "6AFBE41D-692E-4650-890B-387620E7B18C",
    "expires": "2019-02-28T15:18:00Z",
    "isFormatLockedIn": true,
    "formats": [
        {
            "reserveId": "6AFBE41D-692E-4650-890B-387620E7B18C",
            "formatType": "ebook-epub-adobe",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-epub-adobe",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-epub-adobe/downloadlink?errorpageurl={errorpageurl}",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-epub-adobe/downloadlink?errorurl={errorurl}&successurl={successurl}",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            }
        },
        {
            "reserveId": "6AFBE41D-692E-4650-890B-387620E7B18C",
            "formatType": "ebook-overdrive",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-overdrive",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats/ebook-overdrive/downloadlink?errorurl={errorurl}&successurl={successurl}",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            }
        }
    ],
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "metadata": {
            "href": "https://api.overdrive.com/v1/collections/v1P0B6/products/6AFBE41D-692E-4650-890B-387620E7B18C/metadata",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "actions": {
        "format": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C/formats",
            "type": "application/json",
            "method": "post",
            "fields": [
                {
                    "name": "reserveId",
                    "value": "6AFBE41D-692E-4650-890B-387620E7B18C"
                },
                {
                    "name": "formatType",
                    "options": [
                        "ebook-epub-adobe",
                        "ebook-kindle",
                        "ebook-epub-open"
                    ]
                }
            ]
        },
        "earlyReturn": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C",
            "method": "delete"
        }
    },
    "checkoutDate": "2019-02-07T15:18:00Z"
}

When you've successfully checked out the title and locked in a format, the linkTemplates section will have a downloadLink for that format. This link template lets you to construct a link to download the title in the format specified (in this case, the ebook-epub-adobe formatType).

If you did not successfully lock in a format, you'll still see a successful 201 response. But, in this case, the isFormatLockedIn will still be false. To see how this response will look, see this example.

Note: The downloadLink for the ebook-overdrive or audiobook-overdrive format is always available when the format is supported.

GET the formats available for a specific title

You can make a GET request to the formats endpoint to retrieve the download links for each available format for a specific checkout.

For ebooks and audiobooks

  • If a format hasn't been locked in, you'll see downloadLinks for the ebook-overdrive, audiobook-overdrive, or ebook-mediado formats.
  • If a format has been locked in, you'll see the locked-in format and ebook-overdrive or audiobook-overdrive.

For streaming videos: You must lock in the format before you can get a download link in a formats GET response.

Here's what a GET request looks like for a title that hasn't been locked into a format (but is available in ebook-overdrive):

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7/formats
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Connection: Keep-Alive

The response includes only the ebook-overdrive format:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 709
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 23 Sep 2013 20:53:45 GMT
Expires: -1

{
    "formats": [
        {
            "formatType": "ebook-overdrive",
            "reserveId": "08F7D7E6-423F-45A6-9A1E-5AE9122C82E7",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7/formats/ebook-overdrive",
                    "type": "application/vnd.overdrive.content.api+json"
                },
                "linkTemplates": {
                    "downloadLink": {
                        "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                         "type": "application/vnd.overdrive.content.api+json"
                    } 
		    "downloadLinkV2": {
                        "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7/formats/ebook-overdrive/downloadlink?errorurl={errorurl}&successurl={successurl}",
                         "type": "application/vnd.overdrive.content.api+json"
                   } 
               }
            }
        }
    ],
    "self": {
        "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/08F7D7E6-423F-45A6-9A1E-5AE9122C82E7/formats",
        "type": "application/vnd.overdrive.content.api+json"
    }
}

Here's what a response looks like for an ebook with the ebook-epub-adobe format locked in:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 1225
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 23 Sep 2013 20:58:41 GMT
Expires: -1

{
    "formats": [
        {
            "formatType": "ebook-epub-adobe",
            "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-epub-adobe",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-epub-adobe/downloadlink?errorpageurl={errorpageurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
		"downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-epub-adobe/downloadlink?errorurl={errorurl}&successurl={successurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            }
        },
        {
            "formatType": "ebook-overdrive",
            "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
		"downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats/ebook-overdrive/downloadlink?errorurl={errorurl}&successurl={successurl}",
                    "type": "application/vnd.overdrive.content.api+json"
                }
            }
        }
    ],
    "self": {
        "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/76C1B7D0-17F4-4C05-8397-C66C17411584/formats",
        "type": "application/vnd.overdrive.content.api+json"
    }
}

Locking in a format after checkout (POST)

If you don't lock in a format at the time of checkout (as described above), you can make a POST request to the formats endpoint that includes the reserveId and the desired formatType.

Here's a sample POST request to lock in a format (audiobook-mp3):

POST https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats
User-Agent: Your application
Authorization: Bearer {OAuth patron access token}
Content-Type: application/json; charset=utf-8
Host: patron.api.overdrive.com
Content-Length: 168
Expect: 100-continue

{
    "fields": [
        {
            "name": "reserveId",
            "value": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6"
        },
        {
            "name": "formatType",
            "value": "audiobook-mp3"
        }
    ]
}

The response looks like this:

201 Created
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 506
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 24 Sep 2013 00:12:21 GMT
Expires: -1
Location: https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3

{
    "formatType": "audiobook-mp3",
    "reserveId": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3",
            "type": "application/vnd.overdrive.content.api+json"
        }
    },
    "linkTemplates": {
        "downloadLink": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorpageurl={errorpageurl}",
            "type": "application/vnd.overdrive.content.api+json"
        }
	"downloadLinkV2": {
            "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl={errorurl}&successurl={successurl}",
            "type": "application/vnd.overdrive.content.api+json"
        }
    }
}

As noted above, when you successfully check out the title and locked in a format, the linkTemplates section will have a downloadLink for that format. This link template lets you to construct a link to download the title in the format specified.

Note: The downloadLink for the ebook-overdrive or audiobook-overdrive format is always available when the format is supported.