OverDrive Developers

Checkouts API

The Checkouts API is your path to borrowing, returning, and checking the status of titles. To use the checkouts endpoint, be sure to send the proper access token for your patron in the "Authorization" header. To get a patron's OAuth access token, you must first authenticate the user using patron authentication.

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.

Using the Checkouts API

Using POST, GET, and DELETE requests, you can use the Checkouts API to do the following:

Available endpoint actions

  • GET patron checkouts: This request returns a current list of the user's borrowed titles or finds a specific title he or she has borrowed.
  • Check out (borrow) a title: POST to this endpoint to borrow a title on the user's behalf. You can also opt to lock in a specific format for a title at the time of checkout.
  • GET formats available for titles: Use this endpoint to see what formats are available for a specific title that a user has borrowed.
  • "Lock in" the format for a title: Use this endpoint to make a POST that "locks in" a specific format for a title and get a downloadLink to use in the Downloads API. You must lock in most formats before you can get the download link for them.
  • Return a title: This DELETE request allows you to return a title on behalf of a user.

GET a list of a patron's checkouts

Below is the example GET request sent to the /v1/patrons/me/checkouts endpoint.

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com

The response includes a list of titles that the authenticated user currently has checked out from his or her library.

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 6781
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 21 Jul 2015 18:54:06 GMT
Expires: -1

{
    "totalItems": 4,
    "totalCheckouts": 2,
    "checkouts": [
        {
            "reserveId": "A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
            "expires": "2015-08-11T18:53:00Z",
            "isFormatLockedIn": false,
            "formats": [
                {
                    "reserveId": "A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
                    "formatType": "audiobook-overdrive",
                    "links": {
                        "self": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/A03EAC2C-C088-46C6-B9E9-59D6C11A3596/formats/audiobook-overdrive",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    },
                    "linkTemplates": {
                        "downloadLink": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/A03EAC2C-C088-46C6-B9E9-59D6C11A3596/formats/audiobook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        },
                        "downloadLinkV2": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/A03EAC2C-C088-46C6-B9E9-59D6C11A3596/formats/audiobook-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/A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P1BBQ0AAA2N/products/A03EAC2C-C088-46C6-B9E9-59D6C11A3596/metadata",
                    "type": "application/vnd.overdrive.api+json"
                },
                "bundledChildren": [
                    {
                        "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4",
                        "type": "application/vnd.overdrive.circulation.api+json"
                    },
                    {
                        "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2",
                        "type": "application/vnd.overdrive.circulation.api+json"
                    }
                ]
            },
            "actions": {
                "format": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/A03EAC2C-C088-46C6-B9E9-59D6C11A3596/formats",
                    "type": "application/json",
                    "method": "post",
                    "fields": [
                        {
                            "name": "reserveId",
                            "value": "A03EAC2C-C088-46C6-B9E9-59D6C11A3596"
                        },
                        {
                            "name": "formatType",
                            "options": [
                                "audiobook-mp3"
                            ]
                        }
                    ]
                },
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/A03EAC2C-C088-46C6-B9E9-59D6C11A3596",
                    "method": "delete"
                }
            },
            "checkoutDate": "2015-07-21T18:53:00Z"
        },
        {
            "reserveId": "B10DD285-BCE0-435A-A011-30BFCB467AE4",
            "expires": "2015-08-11T18:53:00Z",
            "isFormatLockedIn": true,
            "formats": [
                {
                    "reserveId": "B10DD285-BCE0-435A-A011-30BFCB467AE4",
                    "formatType": "ebook-pdf-adobe",
                    "links": {
                        "self": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4/formats/ebook-pdf-adobe",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    },
                    "linkTemplates": {
                        "downloadLink": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4/formats/ebook-pdf-adobe/downloadlink?errorpageurl={errorpageurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        },
                        "downloadLinkV2": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4/formats/ebook-pdf-adobe/downloadlink?errorurl={errorurl}&successurl={successurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    }
                }
            ],
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P1BBQ0AAA2N/products/B10DD285-BCE0-435A-A011-30BFCB467AE4/metadata",
                    "type": "application/vnd.overdrive.api+json"
                }
            },
			"actions": {
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B10DD285-BCE0-435A-A011-30BFCB467AE4",
                    "method": "delete"
                }
            },
            "checkoutDate": "2015-07-21T18:53:00Z"
        },
        {
            "reserveId": "CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2",
            "expires": "2015-08-11T18:53:00Z",
            "isFormatLockedIn": true,
            "formats": [
                {
                    "reserveId": "CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2",
                    "formatType": "ebook-epub-adobe",
                    "links": {
                        "self": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2/formats/ebook-epub-adobe",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    },
                    "linkTemplates": {
                        "downloadLink": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2/formats/ebook-epub-adobe/downloadlink?errorpageurl={errorpageurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        },
                        "downloadLinkV2": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2/formats/ebook-epub-adobe/downloadlink?errorurl={errorurl}&successurl={successurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    }
                }
            ],
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P1BBQ0AAA2N/products/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2/metadata",
                    "type": "application/vnd.overdrive.api+json"
                }
            },
            "actions": {
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/CE0DF567-53E1-4992-9C1F-5EB93BC8FEC2",
                    "method": "delete"
                }
            },
            "checkoutDate": "2015-07-21T18:53:00Z"
        },
        {
            "reserveId": "13714F86-7A9C-4BA6-80B4-BC8A83DE8615",
            "expires": "2015-08-11T18:53:00Z",
            "isFormatLockedIn": false,
            "formats": [
                {
                    "reserveId": "13714F86-7A9C-4BA6-80B4-BC8A83DE8615",
                    "formatType": "audiobook-overdrive",
                    "links": {
                        "self": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/13714F86-7A9C-4BA6-80B4-BC8A83DE8615/formats/audiobook-overdrive",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        }
                    },
                    "linkTemplates": {
                        "downloadLink": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/13714F86-7A9C-4BA6-80B4-BC8A83DE8615/formats/audiobook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                            "type": "application/vnd.overdrive.circulation.api+json"
                        },
                        "downloadLinkV2": {
                            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/13714F86-7A9C-4BA6-80B4-BC8A83DE8615/formats/audiobook-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/13714F86-7A9C-4BA6-80B4-BC8A83DE8615",
                    "type": "application/vnd.overdrive.circulation.api+json"
                },
                "metadata": {
                    "href": "https://api.overdrive.com/v1/collections/v1P1BBQ0AAA2N/products/13714F86-7A9C-4BA6-80B4-BC8A83DE8615/metadata",
                    "type": "application/vnd.overdrive.api+json"
                }
            },
            "actions": {
                "format": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/13714F86-7A9C-4BA6-80B4-BC8A83DE8615/formats",
                    "type": "application/json",
                    "method": "post",
                    "fields": [
                        {
                            "name": "reserveId",
                            "value": "13714F86-7A9C-4BA6-80B4-BC8A83DE8615"
                        },
                        {
                            "name": "formatType",
                            "options": [
                                "audiobook-mp3"
                            ]
                        }
                    ]
                },
                "earlyReturn": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/13714F86-7A9C-4BA6-80B4-BC8A83DE8615",
                    "method": "delete"
                }
            },
            "checkoutDate": "2015-07-21T18:53:00Z"
        }
    ],
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts",
            "type": "application/vnd.overdrive.circulation.api+json"
        }
    }
}

Use the hypermedia links in the checkouts response to make calls to other APIs for more information on a given title (like Metadata). You can also perform actions, like locking in a format (via the format action) or returning a book on a user's behalf (via the earlyReturn action).

To get information about a specific checkout, you can include the reserveId on the checkouts endpoint GET request.

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 1533
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Thu, 26 Sep 2013 13:25:14 GMT
Expires: -1

{
    "reserveId": "B05CDA64-E444-4749-8B7C-6CC7B7B374BE",
    "expires": "2013-12-31T20:05:00Z",
    "isFormatLockedIn": false,
    "formats": [
        {
            "reserveId": "B05CDA64-E444-4749-8B7C-6CC7B7B374BE",
            "formatType": "ebook-overdrive",
            "links": {
                "self": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE/formats/ebook-overdrive",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
            },
            "linkTemplates": {
                "downloadLink": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}",
                    "type": "application/vnd.overdrive.circulation.api+json"
                }
		"downloadLinkV2": {
                    "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE/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/B05CDA64-E444-4749-8B7C-6CC7B7B374BE",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "metadata": {
            "href": "https://api.overdrive.com/v1/collections/v1P1BBQ0AAA2N/products/B05CDA64-E444-4749-8B7C-6CC7B7B374BE/metadata",
            "type": "application/vnd.overdrive.api+json"
        }
            },
    "actions": {
        "format": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE/formats",
            "type": "application/json",
            "method": "post",
            "fields": [
                {
                    "name": "reserveId",
                    "value": "B05CDA64-E444-4749-8B7C-6CC7B7B374BE",
                    "optional": false
                },
                {
                    "name": "formatType",
                    "value": "",
                    "options": [
                        "ebook-pdf-adobe",
                        "ebook-epub-adobe"
                    ],
                    "optional": false
                }
            ]
        },
        "earlyReturn": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/B05CDA64-E444-4749-8B7C-6CC7B7B374BE",
            "method": "delete"
        }
    }
}

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: integration-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://integration.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.dev.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.dev.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.dev.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.dev.overdrive.com/v1/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.dev.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.dev.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.dev.overdrive.com/v1/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.dev.overdrive.com/v1/patrons/me/checkouts/6AFBE41D-692E-4650-890B-387620E7B18C",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "metadata": {
            "href": "https://api.dev.overdrive.com/v1/collections/v1P0B6/products/6AFBE41D-692E-4650-890B-387620E7B18C/metadata",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "actions": {
        "format": {
            "href": "https://patron-api.dev.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.dev.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/v1/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 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/v1/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.

Returning a title (DELETE)

Titles are automatically returned once their lending period expires, but you can return a book on a user's behalf before then by making a DELETE request to the checkouts endpoint.

Here's a sample DELETE request to return a title:

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

The response will show a "204 NoContent" message when the return has been completed successfully.

204 NoContent
Pragma: no-cache
X-Frame-Options: deny
Cache-Control: no-cache
Date: Tue, 24 Sep 2013 00:52:17 GMT
Expires: -1