Holds and ILL
There are several use cases when placing a hold request in the Wise system. Before a hold can be placed in the system, it is first necessary get the hold information from Wise. The result gives information about whether or not a hold can be placed, possible costs, and pickup locations.
Note: Before using any of the described endpoints, a patron must be logged in and have a valid token.
The Wise Rest-API has 2 pairs of endpoints for preparing and placing holds:
- Prepare and place a hold on a single title/item.
- Prepare and place a hold on multiple titles.
These endpoints can be used in two ways:
- An item will be delivered for every title.
- One item will be delivered for one of the titles. The first item that is found and checked in.
Single hold
The first step for placing a hold on a title is to get the hold information and to check if a hold is allowed for the title:
Prepare hold:
GET /patron/{patronSystemId}/libraryId/{libraryId}/prepareHold/{titleNr}/branch/{branch}
The patron must be logged in before the endpoint can be called. You will need a title number and the patron's home branch.
The response gives information on the following:
- holdPossible: true if a hold can be created for this title
- pickupLocation: this branch is the current pickup location
- pickupLocations: alternative locations
- reserverationCostDetails: costs regarding placing, pickup, and lending fee (if applicable)
- illAllowed: true if a hold can be created for items that aren’t available in the patron's library
- holdParameters: illAllowed is only available if the holds searchStrategy contains an “R” (region-level holds) and/or “I” (system-level holds). For more information on holds settings, see Holds and ILL.
Example:
{
"id": "",
"validationErrors": [],
"holdPossible": true,
"chooseIssueFirst": false,
"pickupLocations": [
{
"branchId": "6491",
"locationType": "B"
},
{
"branchId": "6492",
"locationType": "B"
},
{
"branchId": "6493",
"locationType": "B"
}
],
"pickupLocation": {
"branchId": "6490",
"locationType": "B"
},
"reservationCostDetails": {
"placementCost": 0.0,
"pickupFee": 0.0,
"lendingFee": 0.0
},
"punchCardPunches": 0,
"holdParameters": "N;N649;BIEB;I649;6490;6490|6491|6492|6493|~~~~|",
"queuePosition": 1,
"messageParameters": [],
"reservationCost": 0.0,
"illAllowed": false
}
Place hold
When the prepareHold answers with holdPossible = true or illAllowed = true, then a hold can be created.
Parameters:
- bibliographicRecordId: title number
- holdParameters: the parameter string received from the prepareHold endpoint
- pickupLocationBranchId: the branch to pickup
- requestDueDate: after this date, the hold will be canceled if it’s not fulfilled. When omitted, then the default dueDate will be calculated as configured in the hold settings. See Holds and ILL for more information on holds settings.
Example:
POST patron/4be868c83ea2f8c03b3e052bb35cf0ff/library/I649/hold
{
"requestDueDate":"2021-07-14",
"bibliographicRecordId":3407533,
"holdParameters": "N;N649;BIEB;I649;6490;6490|6491|6492|6493|~~~~|",
"pickupLocationBranchId":"6490"
}
The example above creates a hold request in the holds network of branch 6490.
Creating an ILL request
When a hold is not possible, but a ILL request is, then a placeHold can be used to create an ILL request, but the holdParameters must be adjusted. By replacing the first position of the holdParameters (“B” or “N”) with an “I”, the hold will become an Internal ILL request in the Wise system.
Multiple Holds
For multiple holds, the endpoints /holdOption and /hold will replace the endpoints discussed in the previous section (/prepareHold and /placeHold). These endpoints give you the ability to create multiple holds in one call. The holds can be grouped together and handled as one hold or as individual holds.
Prepare multiple holds
The application needs to check if creating a hold is allowed before a hold can be created.
Parameters:
- bibliographicRecordId: one or more title numbers
- holdType:
- ONE means all titles will be grouped together, and as soon as an item is linked to the request all other requests are cancelled.
- ALL will result in individual holds and will be handled independently.
PUT /restapi/patron/{patronSystemId}/holdoption
{
"titleHoldOptions":[
{
"bibliographicRecordId":"1137719"
},
{
"bibliographicRecordId":"4595"
}
],
"holdType":"ONE",
"pickupBranchId":"6490"
}
Response:
{
"id":"",
"validationErrors":[
],
"pickupBranchId":"6490",
"titleHoldOptions":[
{
"bibliographicRecordId":1137719,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":false
},
{
"bibliographicRecordId":4595,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":true
}
],
"holdType":"ONE",
"altPickupBranches":[
{
"locationNumber":"6491",
"locationType":"B",
"description":"Negenmanneke"
},
{
"locationNumber":"6492",
"locationType":"B",
"description":"Ruisbroek"
},
{
"locationNumber":"6493",
"locationType":"B",
"description":"Vlezenbeek"
}
],
"reservationCostDetails":{
"placementCost":0,
"pickupFee":0,
"punchCardPunches":0
}
searchStrategy":"BRANCH"
}
The response gives information on the following:
- holdAllowed: true if a hold can be created for this title on all levels (library/network/region/system)*
- fastDeliveryAllowed: true if one or more items are available in the library; when a hold is created as fastDelivery the fastDelivery costs are applied
- pickupLocation: this branch is the current pickup location
- pickupLocations: alternative locations
- reserverationCostDetails: costs regarding placing, pickup, and lending fees
- illAllowed: true if a hold can be created for items that aren’t available in the patron's library.*
fastDeliveryAllowed will be available when the system option FASTDEL is activated. The FASTDEL option can be combined with FASTDEN:
- FASTDEL: If an item of the requested title is available in the pickup location, then fastDeliveryAllowed will be true and the fast delivery costs are presented instead of the default hold costs.
- FASTDEN: This is an addition to FASTDEL. Now the system will respond with fastDeliveryAllowed = true when an item is available in the holds network of the library.
* illAllowed is only available if the holds searchStrategy contains an “R” (region level holds) and/or an “I” (system level holds). See Search strategies for more information. To check if a hold will be on Region of System level, the API client should first check if illAllowed is true. If not, the hold will be placed on branch/network level if holdAllowed is true.
Multiple place holds
This endpoint can be used to create one or more holds on multiple titles as a group or as individual holds.
Parameters:
- bibliographicRecordId: title number
- fastDeliveryAllowed: create the hold and apply the fast delivery costs instead of the placement costs.
- holdType:
- ONE means all titles will be grouped together and as soon as an item is linked to the reservation, all other reservations are cancelled.
- ALL will result in individual holds and will be handled independently
- requestDueDate: the date until the hold will be active. After this date, the hold will be canceled if it’s not fulfilled. When omitted, then the default dueDate will be calculated as configured in the hold settings.
Request:
POST patron/4be868c83ea2f8c03b3e052bb35cf0ff/hold
{
"holds":[
{
"bibliographicRecordId":1137719,
"fastDeliveryAllowed":"false",
},
{
"bibliographicRecordId":4595,
"fastDeliveryAllowed":"false",
}
],
"holdType":"ONE",
"pickupBranchId":"6490"
“searchStrategy":"BRANCH" Is hier een Default?
}
Response
{
"id":"",
"validationErrors":[
],
"groupHoldId":617984,
"pickupBranchId":"6490",
"holds":[
{
"bibliographicRecordId":1137719,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":false
},
{
"bibliographicRecordId":4595,
"issueId":"",
"holdAllowed":true,
"fastDeliveryAllowed":false,
"queuePosition":1,
"illAllowed":true
}
],
"holdType":"ONE",
"reservationCostDetails":{
"placementCost":0,
"pickupFee":0,
"punchCardPunches":0
},
"searchStrategy":"BRANCH"
}
Get Holds
The GET method of the holds endpoint gives all active holds of a patron.
GET patron/{patronSystemId}/library/{libraryId}/hold
Response
The response contains the following properties for every hold:
- holdNumber: reference number for this hold
- groupHoldId: reference to other holds in case of holdType “ONE” with multiple titles is created
- bibliographicRecordId: title number of title
- holdStatus: status of this hold
- queuePosition: position in hold queue (approximate)
{
"id":"",
"validationErrors":[
],
"offset":0,
"limit":50,
"total":2,
"items":[
{
"id":"617985",
"validationErrors":[
],
"libraryId":"",
"itemId":0,
"bibliographicRecordId":"4595",
"holdStatus":"ACTIVE",
"cancelAllowed":true,
"updateAllowed":true,
"awaitingPickup":false,
"title":"Gebrandschilderd glas",
"author":"Lee, Lawrence",
"pickupLocationBranchId":"6490",
"pickupLocationName":"libraryName",
"requestDueDate":"2022-06-10",
"holdPlacedDate":"2021-06-10",
"queuePosition":1,
"momkeys":"vlc=13388;isbn=9789027481108;key=4595;",
"medium":"BOE",
"holdNumber":"21061000002",
"groupHoldId":617984
},
{
"id":"617984",
"validationErrors":[
],
"libraryId":"",
"itemId":0,
"bibliographicRecordId":"1137719",
"holdStatus":"ACTIVE",
"cancelAllowed":true,
"updateAllowed":true,
"awaitingPickup":false,
"title":"Het grote boek van waar of niet waar?",
"author":"Mills, Andrea",
"pickupLocationBranchId":"6490",
"pickupLocationName":"Sint-Pieters-Leeuw",
"requestDueDate":"2022-06-10",
"holdPlacedDate":"2021-06-10",
"queuePosition":1,
"momkeys":"vlc=9310024;isbn=9789002258008;key=1137719;",
"medium":"BOE",
"holdNumber":"21061000001",
"groupHoldId":617984
}
]
}