Holds

General Purpose

The resource may be accessed with a GET method to retrieve a specific patron’s holds information. The holds information may be retrieved as a patron’s holds list, or as a specific hold’s information. The holds list information is exported per institution (ADM library).

The resource may be accessed with a DELETE method to cancel a hold request.

Product Version Compatibility

Versions 18, 20.1 and later

Interface Type

RESTful API

Hierarchy

GET - retrieve a specific patrons holds information

 

Input Parameters

REST Resource IDs:

Patron ID: The Aleph patron system identifier.

Hold ID: The ID of the specific hold that is requested. May be used to fetch a specific hold’s information.

URL Parameters:

institution: The ID of an institution (ADM library) for which the information is requested. Optional.

type: The type of hold information that is requested. The value history is used to specify that hold request history is requested. Optional.
For history type, only hold request are reported (z37h-type=h);
title requests are not included within history information.

view: The format in which the holds list will be displayed. Possible values are brief and full. Optional.

Input URI

Holds List:

<Base URL>:/patron/<patron ID>/circulationActions/requests/holds?institution=<Institution ID>

For example:

To retrieve the holds list for the patron ID 00000036, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds

To retrieve the hold requests history list for the patron ID 00000036, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds?type=history

To retrieve the holds list for the patron ID 00000036 for a specific institution, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds?institution=USM50

To retrieve the holds list for the patron ID 00000036 in brief format, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds?view=brief

To retrieve the holds list for the patron ID 00000036 in full format, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds?view=full

Specific Hold:

<Base URL>:/patron/<patron ID</circulationActions/requests/holds/<hold ID>

For example:

To retrieve a specific hold’s information for the patron ID 00000036, use:

http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/USM500000002150001000001

Delete Specific Hold:

Use the same URL with a DELETE method (HTTP method) – to cancel a hold request.

Output XML Format

The returned XML includes the patron’s holds lists per institution, or a specific hold’s information. The information is exported as Z37,Z30 and Z13 tags, in addition to a special status tag that reports the request’s status. When setting the view parameter to full, the records are fully extracted. When setting the view parameter to brief, only some of the elements are extracted.

Note the delete attribute, which indicates whether or not the request may be cancelled in a DELETE action.

The list of institutes can be limited to those in which the patron is active, depending on the institute’s setup of the FILTER-LIBRARY-CARD tab100 variable.

Holds list example:

<?xml version="1.0" encoding="UTF-8"?>
<pat-hold-list>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <hold-requests>
    <hold-request delete="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/TITLE000000003"/>
    <hold-request delete="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/TITLE000000004"/>
    <institution code="USM50">
      <inst-name>Exlibris Demo Libraries</inst-name>
      <hold-request delete="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/USM500000002150001000001"/>
      <hold-request delete="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/USM500000002270000600001"/>
      <hold-request delete="Y" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/requests/holds/USM500000002150000100001"/>
    </institution>
    <institution code="USM51">
      <inst-name>USM51 Demo Libraries</inst-name>
    </institution>
    <institution code="MAB50">
      <inst-name>MAB Demo Library</inst-name>
    </institution>
  </hold-requests>
</pat-hold-list>

Specific hold example:

<?xml version="1.0" encoding="UTF-8"?>
<get-pat-hold>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <hold-request delete="N">
    <status>In process</status>
    <z37>
      <translate-change-active-library>USM50</translate-change-active-library>
      <z37-doc-number>000000215</z37-doc-number>
      <z37-item-sequence>000100</z37-item-sequence>
      <z37-sequence>0001</z37-sequence>
      <z37-id>00000036</z37-id>
      <z37-status>In process</z37-status>
      <z37-expand>Y</z37-expand>
      <z37-priority>05</z37-priority>
      <z37-open-date>20060228</z37-open-date>
      <z37-open-hour>1110</z37-open-hour>
      <z37-request-date>20060228</z37-request-date>
      <z37-end-request-date>20060828</z37-end-request-date>
      <z37-hold-date>00000000</z37-hold-date>
      <z37-letter-status/>
      <z37-letter-date>00000000</z37-letter-date>
      <z37-alpha>L</z37-alpha>
      <z37-author/>
      <z37-title/>
      <z37-pages/>
      <z37-note-1/>
      <z37-note-2/>
      <z37-print-status>P</z37-print-status>
      <z37-requester-id/>
      <z37-cataloger-name>MASTER</z37-cataloger-name>
      <z37-cataloger-ip>10.1.235.173</z37-cataloger-ip>
      <z37-hold-sequence>000</z37-hold-sequence>
      <z37-pickup-location>Law Library</z37-pickup-location>
      <z37-send-action>01</z37-send-action>
      <z37-end-hold-date>00000000</z37-end-hold-date>
      <z37-recall-type>01</z37-recall-type>
      <z37-rush-request>No</z37-rush-request>
      <z37-filter-sub-library>WID</z37-filter-sub-library>
      <z37-filter-item-status>01</z37-filter-item-status>
      <z37-filter-process-status/>
      <z37-filter-collection>GEN</z37-filter-collection>
      <z37-filter-copy>00000</z37-filter-copy>
      <z37-enumeration-a/>
      <z37-enumeration-b/>
      <z37-enumeration-c/>
      <z37-chronological-i/>
      <z37-chronological-j/>
      <z37-chronological-k/>
      <z37-request-type>Hold Request</z37-request-type>
      <z37-booking-start-date>00000000</z37-booking-start-date>
      <z37-booking-start-hour>0000</z37-booking-start-hour>
      <z37-booking-end-date>00000000</z37-booking-end-date>
      <z37-booking-end-hour>0000</z37-booking-end-hour>
      <z37-booking-orig-start-time/>
      <z37-booking-orig-end-time/>
      <z37-release-time/>
      <z37-delivery-time/>
      <z37-head-time/>
      <z37-tail-time/>
      <z37-delivery-sub-location/>
      <z37-return-location/>
      <z37-return-sub-location/>
      <z37-delivery-method/>
      <z37-effective-start-time/>
      <z37-effective-end-time/>
      <z37-request-number>000000844</z37-request-number>
      <z37-group-id>000000000</z37-group-id>
      <z37-group-sequence>000000</z37-group-sequence>
      <z37-balancer-status/>
      <z37-balancer-date>00000000</z37-balancer-date>
      <z37-request-identifier/>
      <z37-requester-name/>
      <z37-upd-time-stamp>200001011200000</z37-upd-time-stamp>
      <z37-cataloger-ip-v6/>
    </z37>
    <z30-sub-library-code>WID</z30-sub-library-code>
    <z30-item-status-code>01</z30-item-status-code>
    <z30-item-process-status-code/>
    <z30-collection-code>GEN</z30-collection-code>
    <z30>
      <translate-change-active-library>USM50</translate-change-active-library>
      <z30-doc-number>000000215</z30-doc-number>
      <z30-item-sequence>   10.0</z30-item-sequence>
      <z30-barcode>32044025727595</z30-barcode>
      <z30-sub-library>Main Library</z30-sub-library>
      <z30-material>Issue (bound)</z30-material>
      <z30-item-status>Regular loan</z30-item-status>
      <z30-open-date>19960326</z30-open-date>
      <z30-update-date>20020123</z30-update-date>
      <z30-cataloger>CONV</z30-cataloger>
      <z30-date-last-return>00000000</z30-date-last-return>
      <z30-hour-last-return>0000</z30-hour-last-return>
      <z30-ip-last-return>CONV</z30-ip-last-return>
      <z30-no-loans>001</z30-no-loans>
      <z30-alpha>L</z30-alpha>
      <z30-collection>General</z30-collection>
      <z30-call-no-type>7</z30-call-no-type>
      <z30-call-no>Celt 149.1.5</z30-call-no>
      <z30-call-no-key>celt      00149 00001 0005 0000 0000</z30-call-no-key>
      <z30-call-no-2-type/>
      <z30-call-no-2/>
      <z30-call-no-2-key/>
      <z30-description>Bd.12 (1996)</z30-description>
      <z30-note-opac/>
      <z30-note-circulation/>
      <z30-note-internal/>
      <z30-order-number/>
      <z30-inventory-number/>
      <z30-inventory-number-date>00000000</z30-inventory-number-date>
      <z30-last-shelf-report-date>00000000</z30-last-shelf-report-date>
      <z30-price/>
      <z30-shelf-report-number/>
      <z30-on-shelf-date>00000000</z30-on-shelf-date>
      <z30-on-shelf-seq>000000</z30-on-shelf-seq>
      <z30-doc-number-2>000000215</z30-doc-number-2>
      <z30-schedule-sequence-2>00000</z30-schedule-sequence-2>
      <z30-copy-sequence-2>00000</z30-copy-sequence-2>
      <z30-vendor-code/>
      <z30-invoice-number/>
      <z30-line-number>00000</z30-line-number>
      <z30-pages/>
      <z30-issue-date>00000000</z30-issue-date>
      <z30-expected-arrival-date>0</z30-expected-arrival-date>
      <z30-arrival-date>0</z30-arrival-date>
      <z30-item-statistic/>
      <z30-item-process-status>Not in Process</z30-item-process-status>
      <z30-copy-id/>
      <z30-hol-doc-number>000000350</z30-hol-doc-number>
      <z30-temp-location>No</z30-temp-location>
      <z30-enumeration-a/>
      <z30-enumeration-b/>
      <z30-enumeration-c/>
      <z30-enumeration-d/>
      <z30-enumeration-e/>
      <z30-enumeration-f/>
      <z30-enumeration-g/>
      <z30-enumeration-h/>
      <z30-chronological-i/>
      <z30-chronological-j/>
      <z30-chronological-k/>
      <z30-chronological-l/>
      <z30-chronological-m/>
      <z30-supp-index-o/>
      <z30-85x-type/>
      <z30-depository-id/>
      <z30-linking-number>000000000</z30-linking-number>
      <z30-gap-indicator/>
      <z30-maintenance-count>000</z30-maintenance-count>
      <z30-process-status-date>00000000</z30-process-status-date>
      <z30-upd-time-stamp>200001011200000</z30-upd-time-stamp>
      <z30-ip-last-return-v6/>
    </z30>
    <z13>
      <translate-change-active-library>USM50</translate-change-active-library>
      <z13-doc-number>000000215</z13-doc-number>
      <z13-year>1959</z13-year>
      <z13-open-date>20040307</z13-open-date>
      <z13-update-date>20040307</z13-update-date>
      <z13-call-no-key/>
      <z13-call-no-code/>
      <z13-call-no/>
      <z13-author-code/>
      <z13-author/>
      <z13-title-code>24500</z13-title-code>
      <z13-title>Buchreihe der Zeitschrift f?r celtische Philologie.</z13-title>
      <z13-imprint-code>26000</z13-imprint-code>
      <z13-imprint>T?bingen : Niemeyer, 1959-</z13-imprint>
      <z13-isbn-issn-code/>
      <z13-isbn-issn/>
      <z13-upd-time-stamp>200001011200000</z13-upd-time-stamp>
    </z13>
  </hold-request>
</get-pat-hold>

Cancel hold example:

<?xml version="1.0" encoding="UTF-8"?>
<del-pat-hold>
  <reply-text>ok</reply-text>
  <reply-code>0000</reply-code>
  <note type="info">Action Succeeded</note>
</del-pat-hold>

Possible Error Codes

01 : The supplied institution ID is invalid

02 : The patron ID is invalid

05 : Request does not belong to the requested patron

08 : Request does not exist

13 : Request Cancellation failed