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 for it 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 that has not yet been locked in to a specific format.

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"
                }
            },
            "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"
                }
            },
            "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, which include the formats and earlyReturn endpoints.

To get information on an individual checkout, you can add the reserveId to the checkouts endpoint.

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.

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"
        }
    ]
}

The specific title borrowed is identified by reserveId with the name and value fields filled in appropriately. 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"
        }
    }
}

Because a format was not locked in during checkout, the format and earlyReturn actions appear in the response.

You'll find the formatType in the format action, which you can use to POST to the formats endpoint to lock one in. Use the example in the section below to see how a POST request to the formats endpoint looks. In this example, you'll choose between ebook-pdf-adobe, ebook-epub-adobe, and ebook-kindle as the available formats to lock in for this title.

Only one format can be locked in per title; however, when the formats are supported, OverDrive Read and OverDrive Listen are always available formats and are not lockable. This means that 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).

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, which looks like this:

201 Created
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 1522
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 23 Sep 2013 15:06:46 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 11:06:00 AM",
    "isFormatLockedIn": true,
    "formats": [
        {
            "reserveId": "76C1B7D0-17F4-4C05-8397-C66C17411584",
            "formatType": "ebook-epub-adobe",
            "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"
                }
            }
        },
        {
            "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"
        }
    }
}

When you've successfully checked out the title and locked in the format, you won't see any actions in the response (since a format has already been locked in). Instead, there is a downloadLink in the linkTemplates section, allowing you to get a download link for the ebook-epub-adobe formatType.

If you did not successfully lock in a format, you'll still see a successful 201 response. However, in this response, you'll have an actions section and the isFormatLockedIn will be false. To see how this response will look, refer to the first example in the section (that doesn't lock in a format).

Note: The downloadLink for the ebook-overdrive format is always available when the format is supported. These are OverDrive Read eBooks which are available to end users regardless of whether or not a format has been locked in. The same is true for audiobooks in the OverDrive Listen (audiobook-overdrive) format.

GET the formats available for a specific title

You can make a GET request to the formats endpoint to see what formats are available for a specific title that a user has borrowed.

For eBooks and audiobooks: If no format has been locked in, the only downloadLink shown will be for 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 video and NOOK periodicals: You must lock in a format to see it in a formats GET response. If you do not select a format, the response will return without a linkTemplates in the links section.

Here's what a formats request looks like for a title (available in ebook-overdrive) that has not yet been locked into a format:

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 as shown below.

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)

Formats can be locked in either at the time of check out through the checkouts endpoint (see example in "Checking out a title"), or independently after a title has been borrowed.

When a title doesn't have a format locked in (like the first title in the GET checkouts response above), the isFormatLockedIn value is false. The actions available for that title are:

  • A POST request to the format rel
  • a DELETE request to the earlyReturn rel

The format action identifies how the request to lock in this title is created. To lock a format after checkout, POST to the formats endpoint and fill in the formatType in the body fields as shown in the example below.

Note: Make sure all of the fields are filled in before making the formats POST.

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"
        }
    ]
}

In this example, the value audiobook-mp3 locks the audiobook into the MP3 format. 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"
        }
    }
}

Note: You won't be able to lock in the ebook-overdrive, audiobook-overdrive, or ebook-mediado formats, as they are always available for compatible titles (even after you lock in another format).

Returning a title (DELETE)

The earlyReturn rel is only available for a title if a format has not yet been locked in. You can see whether a format has been locked in by the isFormatLockedIn property. If a format has been locked in, then users need to use software like the OverDrive app or Adobe Digital Editions to complete the return process. Once the lending period expires for a given title, it is automatically returned.

Titles can be returned by making a DELETE request to the checkouts endpoint. Below is an example of a DELETE (earlyReturn) request.

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