The Patron API - Holds

The Patron API contains methods for creating, retrieving, updating, and deleting holds for a patron. Using these endpoints, you can:

The Try it out! links below take you to the corresponding section in the interactive documentation, where you can view the model, model schema, and parameters for each available operation.

Get a Hold Record by Hold ID

To use this endpoint, your key must be assigned the Patrons Read or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

GET /v6/patrons/holds/{holdId}

Returns a single Hold object.

Try it out!

Modify a Hold

To use this endpoint, your key must be assigned the Patrons Write or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

PUT /v6/patrons/holds/{holdId}

Modifies a specified hold. Requires a PatronHoldPut request object.

Try it out!

Delete a Hold by Hold ID

To use this endpoint, your key must be assigned the Patrons Write or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

DELETE /v6/patrons/holds/{holdId}

Deletes a specified hold.

Try it out!

Get the Holds Data for a Single Patron Record

To use this endpoint, your key must be assigned the Patrons Read or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

GET /v6/patrons/{id}/holds

Returns all holds data for a specified patron record.

Try it out!

Get All Patrons Holds Data

This endpoint is available in Sierra 5.2 and later. To use this endpoint, your key must be assigned the Holds Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

GET /v6/patrons/holds

Returns the combined total number of bibliographic-, item-, and volume-level holds in the system and a Hold object for each hold.

By default, this endpoint returns the first 50 results. You can limit the number of results to a value from 1 to 2000 and specify the beginning record to return. See Pagination Parameters for more information on using these limiters.

Try it out!

Cancel All Holds for the Specified Patron

To use this endpoint, your key must be assigned the Patrons Write or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

DELETE /v6/patrons/{id}/holds

Cancels all holds for the specified patron record.

Try it out!

Place a New Hold Request

To use this endpoint, your key must be assigned the Patrons Write or Patrons Holds CRUD role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

POST /v6/patrons/{id}/holds/requests

Places a new hold request for the specified patron record. Requires a PatronHoldPost request object.

If successful, HTTP 204 is returned. Otherwise, an error code is returned.

Under certain circumstances, Sierra API returns error code 156 and prompts you to choose a specific volume. Click on "Placing a Hold for a Volume" below for more information.

Sierra API returns the volume information described below in Sierra 5.0 and later.

If a bibliographic record has volume records or item records with volume fields (often referred to as "v-tagged item records") linked to it, you cannot place a bibliographic-level hold on that record. If you attempt to do so, Sierra API returns information about the volumes linked to the bibliographic record and prompts you to choose one. The information provided depends on which record type (volume or v-tagged item record) is attached to the bibliographic record.

V-Tagged Item Records

If the bibliographic record has attached v-tagged item records, Sierra API returns a message similar to the one below. The itemAsVolumes property contains information about each v-tagged item linked to that bibliographic record, including the item record number in the id element. 

{
   "details": {
      "itemsAsVolumes": [
         {
           "id": 1986569,
           "available": true,
           "location":
              { "code": "beanf", "name": "Bellevue NonFiction" },
           "status":
              { "code": "z", "display": "CLMS RETD" },
           "callNumber": "623.44 MOD 2001"
	     },
         {
           "id": 1986571,
           "available": true,
           "location":
              { "code": "ktanf", "name": "Kent NonFiction" },
           "status":
              { "code": "-", "display": "AVAILABLE" },
           "callNumber": "623.44 MOD 2001"
         }
	   ],
      "volumes": [],
   },
   "code": 156,
   "specificCode": 0,
   "httpStatus": 400,
   "name": "Volume record selection is required to proceed."
}

Volume Records

If the bibliographic record has attached volume records, Sierra API displays a message similar to the one below. The volumes property contains information about each volume, including the volume record number in the id element. 

{
   "details": {
      "itemsAsVolumes": [],
      "volumes": [
         { "id": 1000450, "name": "Series 1" },
         { "id": 1000451, "name": "Series 2" },
         { "id": 1000452, "name": "Series 3" }
      ]
   },
   "code": 156,
   "specificCode": 0,
   "httpStatus": 400,
   "name": "Volume record selection is required to proceed."
}

Try it out!