Ready to Learn?Ex Libris products all provide open APIs

Hold per Item

Hold per Item

General Purpose

The resource may be accessed with a GET method to retrieve the hold request information for a specific patron and item. The hold request information includes the pickup location information and other information that the patron may submit when creating an item-level hold request.

The resource may be accessed with a PUT method to create a hold request for a specific patron and on a specific item.

Product Version Compatibility

Versions 18, 20.1 and later

Interface Type






Input Parameters

REST Resource IDs:

Patron ID: The Aleph patron system identifier.

Record ID: The Aleph BIB record identifier. The identifier is composed of the BIB library code + the system number. For example, USM01000050362

Item ID: The Aleph item record identifier. The item ID may be used to fetch a specific item's information. The identifier is composed of the ADM library code + the item record key. For example, USM50000238843000320.

Input URI

<Base URL>:patron/<patron ID>/record/<record ID>/items/<Item ID>/hold

For example:

To retrieve the hold request information for a specific item that belongs to BIB record 00030437 and for the patron ID 00000036, use:

Input XML

To create a new item-level hold request, use the same URL with a PUT method of HTTP.
The request "Body" of the "PUT" method must contain input XML with the Hold request details.
The PUT XML must have the following structure:

post_xml=<hold-request-parameters><pickup-location>WID</pickup-location><last-interest-date>20141231</last-interest-date><start-interest-date>20140917</start-interest-date><sub-author>Additional Author Information</sub-author><sub-title>Additional Title Information</sub-title><pages>Additional Pages Information</pages><note-1>Additional Note</note-1><note-2>Additional Note</note-2><rush>Y or N</rush></hold-request-parameters>
Note that the date information must be in YYYYMMDD format. The pickup location must be supplied as code.
Also note the "post_xml=" on start.

Output XML Format

The returned XML includes information to enable the patron to create a hold request on the item. For example, the response includes a list of the allowed pickup locations. Every field that is marked with the usage attribute may be used by the patron for creating the hold request.

For example:

<?xml version="1.0" encoding="UTF-8"?>
  <hold allowed="Y">
    <pickup-locations default="Y" usage="Mandatory">
      <pickup-location code="LAW">Law Library</pickup-location>
      <pickup-location code="LIT">Economics Library</pickup-location>
    <note type="info">Item is on an open shelf.</note>
    <note type="info">Item status: Regular loan (01) Call number: PQ2631.R63 A72 1992x,</note>
    <note type="info">Item Description: vol. 1</note>
    <note type="info">Requested item has a like copy on shelf.</note>
    <last-interest-date usage="Optional">20140307</last-interest-date>
    <start-interest-date usage="Optional"/>
    <sub-author usage="Optional" max_len="50"/>
    <sub-title usage="Optional" max_len="100"/>
    <pages usage="Optional" max_len="30"/>
    <note-1 usage="Optional" max_len="50"/>
    <note-2 usage="Optional" max_len="50"/>
    <rush usage="Optional"/>
Note that the date information must be in YYYYMMDD format. The pickup location must be supplied as code.
If a new request was successfully created using the POST method, a reply such as the following will be reported:
<?xml version="1.0" encoding="UTF-8"?>
    <note type="info">Action Succeeded</note>

Possible Error Codes

02 : The patron ID is invalid

19 : Record does not exist

25 : Failed to create  request

27 : Item does not exist