Add Local Hold Request

POST /api/.../holds?bulkmode=false&isORSStaffNoteManuallySupplied=false

Place a local hold request for a patron at either the bibliographic or item level.

The 'bulkmode' option is used to limit functionality and conversation steps if hold requests are being created in bulk. Currently, the only steps that are skipped are the checks for serials and multi-part monograph holds processing. This is an optional parameter. The default value is 'false'.

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 or item data that needs to be included will be pulled from the bibliographic and/or item records 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.

Request Information

Parameters

The process of adding a hold request is "conversational" in nature. Multiple API requests may have to be made as the user may need to acknowledge, bypass, or otherwise answer questions. As such, along with the actual hold request data, additional procedural state information will be passed back and forth.

The body of the REQUEST calls to the API will follow this general pattern:

{
    ProcedureStep: 20,
    Answer: 1,
    ActivationDate: "2013-11-22",
    BibliographicRecordID: 26,
    ExpirationDate: "11/30/2013",
    Origin: 1,
    PatronID: 357971,
    PickupBranchID: 13
}

The body of the RETURNED calls will follow this general pattern:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests: null,
    DesignationsOrVolumes: null,
    MaxHoldMaterialTypes: null,
    PAPIProcedure: 0,
    PAPIProcedureStep: 2,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 4,
    PAPIStopType: 0,
    PAPIReturnCode: -4008,
    PatronBlocks: null,
    LinkedPatronBlocks: null,
    Success: false,
    Message: "Patron is blocked.  Do you want to continue with this operation?"
}

Workflow Steps

The initial API request should have a ProcedureStep value of 1 (Start). Check the returned values for the Success attribute as an indication if adding the new hold request was successful. If Success is true, the HoldRequestID attribute will contain the ID of the newly created hold request.

If the 'Pre-Check Add Local Hold Request' API call has been previously called, you may bypass the checking of patron blocks in this call by using an initial ProcedureStep value of '23' (PreCheckVerified).

For cases where Success is false, check the other PAPI* attributes for what is required next in order to resubmit the API request. The PAPIProcedureStep may contain any of the following values if the Success attribute is false:

• 2 - Patron is blocked (can be bypassed)
• 20 - Title is not holdable (can be bypassed)
• 21 - Duplicate hold requests exist (can be bypassed)
• 22 - Patron already has maximum number of holds total or by material type (can be bypassed)
• 25 - Select a specific designation (list of possible values is returned in the DesignationsOrVolumes attribute)
• 26 - Select a specific volume (list of possible values is returned in the DesignationsOrVolumes attribute)
• 27 - Prompt for whether a specific item or serial should be used for hold request
• 28 - Prompt for whether or not to promote an item-level request to a bib level (related to serials/multi-part monograph processing)
• 32 - Patron already has maximum number of holds by material type (can be bypassed)

Continue this workflow until PAPIStopType comes back as 1 (Exit) or the HoldRequestID attribute is > 0, and there are no further procedure steps.

For PAPIProcedureStep 20 (title is not holdable), 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
• This item is marked 'Do not mail to patron'
• Hold request not permitted
• The item record is Provisional
• The item record is Deleted.

For PAPIProcedureStep 20 (title is not holdable), the following are reasons a hold request is blocked and CAN be bypassed:

• No items are attached to the bibliographic record
• An item at this branch is IN
• All items have a prohibited status and will not fill this request
• All items are restricted from filling this request
• All items are restricted from filling this request according to their assigned branch policy
• All items will not fill this request because they do not belong to a responder branch for this pickup location
• The item is IN
• The item has a prohibited status and is not available to fill your request
• This item is not holdable
• This item cannot fill the request according to its assigned branch policy
• This item will not fill this request because it does not belong to a responder branch for this pickup location
• This multipart item is restricted from filling requests
• This serial item is restricted from filling requests

For PAPIProcedureStep 2 (patron blocks), summary data for the list of patron blocks will be returned in the PatronBlocks and LinkedPatronBlocks properties. (See the 'Patron Blocks' API call for more detailed information on the format of the data in those lists). They can be displayed to the user for acknowlegment or bypass. The data is returned in the following format:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests: null,
    DesignationsOrVolumes: null,
    PatronBlocks:
    [
        {
            PatronID: 222,
            PatronFullName: "John Smith",
            BlockType: 1,
            BlockID: 45629,
            BlockDescription: "Test Block Description"
        },
        {
            PatronID: 222,
            PatronFullName: "John Smith",
            BlockType: 1,
            BlockID: 45631,
            BlockDescription: "Patron has overdue items"
        },
        {
            PatronID: 222,
            PatronFullName: "John Smith",
            BlockType: 1,
            BlockID: 45632,
            BlockDescription: "Verify Address"
        }
    ],
    LinkedPatronBlocks:
    [
        {
            PatronID: 2143,
            PatronFullName: "Jane Smith",
            BlockType: 1,
            BlockID: 4563,
            BlockDescription: "Test Block Description"
        }
    ],
    MaxHoldMaterialTypes: null,
    PAPIProcedure: 0,
    PAPIProcedureStep: 2,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 4,
    PAPIStopType: 0,
    PAPIReturnCode: -4008,
    Success: false,
    Message: "Patron is blocked.  Do you want to continue with this operation?"
}

For PAPIProcedureStep 21 (duplicate hold requests exist), summary data for the list of duplicate hold requests will be returned in the DuplicateHoldRequests attribute. They can be displayed to the user for acknowlegment or bypass. The data is returned in the following format:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests:
    [
        {
            SysHoldRequestID: 0,
            BrowseAuthor: "Galvin, Patrick J.",
            BrowseTitle: "Finishing off",
            FormatDescription: "Book",
            CreationDate: "2013-08-12T09:23:38.487",
            PickupBranch: "Amsterdam Free Library"
        },
        {
            SysHoldRequestID: 0,
            BrowseAuthor: "Galvin, Patrick J.",
            BrowseTitle: "Finishing off",
            FormatDescription: "Book",
            CreationDate: "2013-10-02T11:54:38.487",
            PickupBranch: "Raquette Lake Public Library"
        },
        {
            SysHoldRequestID: 0,
            BrowseAuthor: "Galvin, Patrick J.",
            BrowseTitle: "Finishing off",
            FormatDescription: "Book",
            CreationDate: "2013-09-18T17:20:56.66",
            PickupBranch: "Main Branch"
        }
    ],
    DesignationsOrVolumes: null,
    MaxHoldMaterialTypes: null,
    PAPIProcedure: 0,
    PAPIProcedureStep: 21,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 4,
    PAPIStopType: 0,
    PAPIReturnCode: -4010,
    Success: false,
    Message: "Duplicate hold requests exist."
}

For PAPIProcedureStep 25 (select a specific designation), a list of unique designation strings will be returned in the DesignationsOrVolumes attribute. They can be displayed to the user for selection or bypass. The data is returned in the following format:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests: null,
    DesignationsOrVolumes:
    [
        "Issue 1",
        "Issue 2",
        "Issue 3",
        "Issue 4",
        "Issue 5"
    ],
    MaxHoldMaterialTypes: null,
    PAPIProcedure: 0,
    PAPIProcedureStep: 25,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 9,
    PAPIStopType: 0,
    PAPIReturnCode: -4012,
    Success: false
}

For PAPIProcedureStep 26 (select a specific volume), a list of unique volume strings will be returned in the DesignationsOrVolumes attribute. They can be displayed to the user for selection or bypass. The data is returned in the following format:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests: null,
    DesignationsOrVolumes:
    [
        "Volume 1",
        "Volume 2",
        "Volume 3",
        "Volume 4",
        "Volume 5"
    ],
    MaxHoldMaterialTypes: null,
    PAPIProcedure: 0,
    PAPIProcedureStep: 26,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 9,
    PAPIStopType: 0,
    PAPIReturnCode: -4012,
    Success: false
}

For PAPIProcedureStep 32 (material type limit reached), a list of material types affected is returned in the MaxHoldMaterialTypes field:

{
    ProcedureStep: null,
    Answer: null,
    HoldRequestID: null,
    DuplicateHoldRequests: null,
    DesignationsOrVolumes: null,
    MaxHoldMaterialTypes: [1, 3],
    PAPIProcedure: 0,
    PAPIProcedureStep: 32,
    PAPIAction: 2,
    PAPIActionProcedure: 0,
    PAPIPromptType: 9,
    PAPIStopType: 0,
    PAPIReturnCode: -4012,
    Success: false
}

POST Form Data

Provide the following in the form/body of the request:

HTTP Response Codes