Create Hold Request for multiple patrons

Start Create Hold Request Process

POST /api/.../workflow

Create a local hold request for multiple patrons in a record set. Requests created are at the bibliographic level. For detailed workflow process information, see Overview.

A typical hold request is "locked". The means that all that needs to be provided in this API call are the fields marked as required below. Any additional bibliographic data that needs to be included will be pulled from the bibliographic record inside the API call.

For "unlocked" hold requests (signify by setting the 'UnlockedRequest' attribute to 'true'), the caller must provide at least the 'Title' attribute plus any additional fields listed below the 'UnlockedRequest' attribute in the table below.

Permissions

This call requires the HoldRequests_Create (ID: 89) permission to create the request and the OverrideRequestBlocks_Allow (ID: 132) permission to override hold request blocks.

Workflow Steps

  • Patron is blocked (can be bypassed).
  • Title is not holdable (can be bypassed)
  • Patron already has maximum number of holds total (can be bypassed)
  • Patron already has maximum number of holds by material type (can be bypassed)
  • Duplicate hold requests exist (can be bypassed)

For title is not holdable step, the following are reasons a hold request is blocked and can NOT be bypassed:

  • Hold request not permitted. The bibliographic record has been created for ILL.
  • The bibliographic record is Provisional
  • The bibliographic record is Deleted
  • Hold request not permitted

For title is not holdable step, the following are reasons a hold request is blocked and CAN be bypassed:

  • No items are attached to the bibliographic record
  • All holdable items attached to bib are IN and IN is restricted
  • All holdable items attached to bib are in restricted state other than IN
  • All items attached to bib not holdable due to holdable (checkbox) restictions
  • All items are restricted from filling this request
  • All items attached to bib not holdable due to hold sequence restrictions
  • All items attached to bib not holdable due to borrow by mail restrictions

Request Information

Parameters
Name Type Required Description
WorkflowRequest DtoWorkflowRequest Yes Define this parameter in the request body.
DtoWorkflowRequest
Property Type Nullable Description
WorkflowRequestType Int No Required. For placing a hold request, this must be set to 29.
TxnBranchID Int No Transacting branch ID. This should represent where the request originated from. Typically the same as the logged on branch, but in the case of offline processing it would be the branch that was logged into during offline processing.
TxnUserID Int No Transacting Polaris user ID. This should represent who originally created this request. Typically the same as the logged on user, but in the case of offline processing it would be the user that was logged on during offline processing.
TxnWorkstationID Int No Transacting workstation ID. This should represent where the request originated from. Typically the same as the logged on workstation, but in the case of offline processing it would be the workstation that was logged into during offline processing.
RequestExtension DtoWorkflowRequestExtension No To place hold request for multiple patrons requires a BulkHoldRequestExtensionData object.
WorkflowReplies List of DtoWorkflowReply Yes It is possible to pass in a list of replies for automated processing.
BulkHoldRequestExtensionData
Property Type Nullable Description
WorkflowRequestExtensionType Int No For placing a hold request for multiple patrons, the extension type must be a 26 (BulkExtensionData).
Data Object No This must be an extension data object of type DtoBulkHoldRequestExtensionData
DtoBulkHoldRequestExtensionData
Property Type Nullable Description
RecordsetID Int No Patron Recordset ID
PickupBranchID Int No
UsePatronPickupBranch Boolean No Currently not used.
Origin String No 1 = PAC, 2 = Staff Client, 3 - NCIPILL
ActivationDate DateTime No Date cannot be in the past
ExpirationDate DateTime No Must be greater than ActivationDate
BibliographicRecordID Int Yes Field is ignored if UnlockedRequest is set to 'true'.
BorrowByMail Boolean Yes
UnlockedRequest Boolean Yes If set to 'true', any of the bibliographic and item fields listed below will be used instead of the data from the associated bibliographic or Item record. If not specified or set to 'false', all of the fields below will be ignored.
Title String No (when UnlockedRequest is true) Max length: 255
Author String Yes Max length: 255
Series String Yes Max length: 255
Publisher String Yes Max length: 50
PublicationYear Int Yes 4 digit string
ISBN String Yes Max length: 50
ISSN String Yes Max length: 50
Edition String Yes Max length: 10
LCCN String Yes Max length: 40
MARCTOMID Int Yes For a list of valid IDs, see Bibliographic Types of Material
Pages String Yes Max length: 255
Designation String Yes Used for "issue" data. Max length: 780
VolumeNumber String Yes Max length: 60

Hold Request Request body

application/json, text/json 
{
    "WorkflowRequestType":29,
    "TxnBranchID":"3",
    "TxnUserID":"1",
    "TxnWorkstationID":"1237",
    "WorkflowReplies":null,
    "RequestExtension":
    {
        "WorkflowRequestExtensionType":26,
        "Data":
        {               
            "RecordsetID":55616,
            "PickupBranchID":"3",
            "Origin":2,
            "ActivationDate":"2020-10-05",
            "ExpirationDate":"2020-10-06",
            "BibliographicRecordID":10654,
            "Designation":null,
            "VolumeNumber":null,
            "ItemLevelHold":false
        }
    },
    "WorkflowReplies":null
}

Response Information

Example - Patron blocks response

Summary data for the list of patron blocks will be returned in the PatronBlocks and LinkedPatronBlocks properties. They can be displayed to the user for acknowlegment or bypass.

application/json, text/json 
{
  "WorkflowRequestGuid": "2c2b1416-ac94-4b31-8bcc-7e5f2a11c0e9",
  "WorkflowRequestType": 29,
  "WorkflowStatus": -3,
  "Prompt": {
    "WorkflowPromptID": 96,
    "Name": null,
    "Description": null,
    "WorkflowPromptType": 3,
    "WorkflowPromptOptions": 6,
    "DefaultPromptOption": 4,
    "Title": "Patron is blocked",
    "Message": "Do you want to continue with this operation?",
    "AlternateMessage": "",
    "AlternateYesText": "",
    "AlternateNoText": "",
    "AlternateCancelText": "",
    "AlternateContinueText": "",
    "PromptExtension": {
      "WorkflowPromptExtensionType": 8,
      "Data": {
        "HeldItemBlock": true,
        "FirstLevelFineBlock": true,
        "UnreadMessageBlock": false,
        "SecondLevelFineBlock": false,
        "OverdueItemBlock": true,
        "ClaimLimitBlock": false,
        "BlockingNoteBlock": false,
        "CollectionAgencyBlock": false,
        "PatronSystemBlock": false,
        "LibraryAssignedBlock": false,
        "FreeTextBlock": false,
        "AssociatedPatronBlock": false,
        "PatronBlocks": [
          {
            "PatronID": 358255,
            "PatronFullName": "Jetson, Astro",
            "BlockType": 3,
            "BlockID": 103,
            "BlockDescription": "Long overdue: 1 of 2",
            "PatronBranchID": 3,
            "CreationDate": null
          },
          {
            "PatronID": 358255,
            "PatronFullName": "Jetson, Astro",
            "BlockType": 3,
            "BlockID": 104,
            "BlockDescription": "Patron owes money. Amount due: $9.23",
            "PatronBranchID": 3,
            "CreationDate": null
          },
          {
            "PatronID": 358255,
            "PatronFullName": "Jetson, Astro",
            "BlockType": 3,
            "BlockID": 106,
            "BlockDescription": "Patron has 1 held items at registered branch of Amsterdam Free Library",
            "PatronBranchID": 3,
            "CreationDate": null
          },
          {
            "PatronID": 358255,
            "PatronFullName": "Jetson, Astro",
            "BlockType": 3,
            "BlockID": 106,
            "BlockDescription": "Patron has 1 held items at branches other than registered branch of Amsterdam Free Library",
            "PatronBranchID": 3,
            "CreationDate": null
          }
        ],
        "LinkedPatronBlocks": []
      }
    }
  },
  "InformationMessages": [],
  "AnswerExtension": null,
  "CircTranType": 0,
  "ReceiptType": 0,
  "ReceiptUrl": "",
  "FineEReceiptSent": false
}
Example - Exceeded total request limit
application/json, text/json 
{
    "WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
    "WorkflowRequestType":29,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":68,"Name":null,
        "Description":null,"WorkflowPromptType":1,
        "WorkflowPromptOptions":6,
        "DefaultPromptOption":4,
        "Title":"Exceeded total request limit",
        "Message":"Patron (వనజ Ramaraos) has exceeded the maximum number of requests permitted.

Title:  Eileen [electronic resource] : A Novel

Do you want to place this request?",
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":null
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}
Example - Material type limit reached
A list of material types affected is returned in the MaxHoldMaterialTypes field.
application/json, text/json 
{
    "WorkflowRequestGuid":"4b31805a-06d9-430a-95ce-404ebfbeddb1",
    "WorkflowRequestType":29,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":21,
        "Name":null,
        "Description":null,
        "WorkflowPromptType":1,"WorkflowPromptOptions":6,
        "DefaultPromptOption":0,
        "Title":"Exceeded material type request limit","Message":"Patron (వనజ Ramaraos) has exceeded request limit for the title.
Title:  Harry Potter and the sorcerer's stone

Patron has made 20 of 5 requests permitted for material type Book.
Do you want to place this request?",
        "AlternateMessage":"",
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":
        {
            "WorkflowPromptExtensionType":34,
            "Data":
            {
                MaxHoldMaterialTypes:[1]
            } 
        }   
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}
Example - Title is blocked
application/json, text/json 
{
"WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
"WorkflowRequestType":29,
"WorkflowStatus":-3,
"Prompt":
{
    "WorkflowPromptID":89,
    "Name":null,
    "Description":null,
    "WorkflowPromptType":1,
    "WorkflowPromptOptions":6,
    "DefaultPromptOption":5,
    "Title":"Title is blocked",
    "Message":"Title: Eileen [electronic resource] : A Novel

All items are restricted from filling this request.

Do you want to place this request?",
    "AlternateYesText":"",
    "AlternateNoText":"",
    "AlternateCancelText":"",
    "AlternateContinueText":"",
    "PromptExtension":null
},
"InformationMessages":[],
"AnswerExtension":null,
"CircTranType":0,
"ReceiptType":0,
"ReceiptUrl":"",
"FineEReceiptSent":false
}
Example -Duplicate hold exists

Summary data for the list of duplicate hold requests will be returned in the DuplicateHolds attribute. They can be displayed to the user for acknowlegment or bypass.

application/json, text/json 
{   
    "WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
    "WorkflowRequestType":29,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":77,
        "Name":null,
        "Description":null,
        "WorkflowPromptType":19,
        "WorkflowPromptOptions":6,
        "DefaultPromptOption":4,
        "Title":"Duplicate Hold requests exist",
        "Message":null,
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":
        {
            "WorkflowPromptExtensionType":31,
            "Data":
            {
                "DuplicateHolds":
                [
                    {
                        "SysHoldRequestID":0,
                        "BrowseAuthor":"Moshfegh, Ottessa.",
                        "BrowseTitle":"Eileen [electronic resource] : A Novel",
                        "FormatDescription":"Ebook",
                        "CreationDate":"2018-04-30T12:01:06.173-04:00",
                        "PickupBranch":"Amsterdam Free Library",
                        "PickupBranchID":3
                    },            
                    {
                        "SysHoldRequestID":0,
                        "BrowseAuthor":"Moshfegh, Ottessa.",
                        "BrowseTitle":"Eileen [electronic resource] : A Novel",
                        "FormatDescription":"Ebook",
                        "CreationDate":"2018-04-30T14:24:42.527-04:00",
                        "PickupBranch":"Amsterdam Free Library",
                        "PickupBranchID":3
                    }
                ]
            }
        }
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}

Hold request Create Response Information

Example: DtoWorkflowAnswer - Place hold request successful
application/json, text/json 
{
    "WorkflowRequestGuid": "85a9bd2a-8910-47f2-a754-a12c2341c02e",
    "WorkflowRequestType": 29,
    "WorkflowStatus": 1,
    "Prompt": null, "InformationMessages": [
    {
      "Type": 1,
      "Title": "",
      "Message": "Hold request is created for 1 patron(s)."
    },
    {
      "Type": 4,
      "Title": "",
      "Message": "Hold request failed to create for 3 patron(s)."
    }
    "AnswerExtension": null,
    "CircTranType": 0,
    "ReceiptType": 0,
    "ReceiptUrl": "",
    "FineEReceiptSent": false
}

HTTP Response Codes

Code Description
200 OK. Check for WorkflowStatus, continue until process is complete.
400

FAILURE due to invalid input or data validation.
409 CONFLICT. Patron record is secured.

Required Permissions

Permission IDs found here.

    CR_HoldRequests_Create,
    CR_AccessCatalogingSubsystem_Allow,
    CR_CatalogingRecordSets_Access,
    CR_PatronRecordSets_Access