FOLIO · Schema

request

Request for an item that might be at a different location or already checked out to another patron

CompanyLibrariesLibrary Services PlatformOpen SourceMicroservicesEducation

Properties

Name	Type	Description
id	string	UUID of the request
requestType	string	Whether the item should be held upon return, recalled or paged for
requestLevel	string	Level of the request - Item or Title
ecsRequestPhase	string	Stage in ECS request process, absence of this field means this is a single-tenant request
requestDate	string	Date the request was made
patronComments	string	Comments made by the patron
requesterId	string	ID of the user who made the request
proxyUserId	string	ID of the user representing a proxy for the patron
instanceId	string	ID of the instance being requested
holdingsRecordId	string	ID of the holdings record being requested
itemId	string	ID of the item being requested
status	string	Status of the request
cancellationReasonId	string	The id of the request reason
cancelledByUserId	string	The id of the user that cancelled the request
cancellationAdditionalInformation	string	Additional information about a cancellation
cancelledDate	string	Date the request was cancelled
position	integer	position of the request in a per-item request queue
instance	object	Copy of some instance metadata (used for searching and sorting)
item	object	Copy of some item metadata (used for searching and sorting)
requester	object	Copy of some requesting patron metadata (used for searching and sorting), will be taken from the user referred to by the requesterId
proxy	object	Copy of some proxy patron metadata (used for searching and sorting), will be taken from the user referred to by the proxyUserId
fulfillmentPreference	string	How should the request be fulfilled (whether the item should be kept on the hold shelf for collection or delivered to the requester)
deliveryAddressTypeId	string	Deliver to the address of this type, for the requesting patron
deliveryAddress	object	Address the item is to be delivered to (derived from requester information)
requestExpirationDate	string	Date when the request expires
holdShelfExpirationDate	string	Date when an item returned to the hold shelf expires
pickupServicePointId	string	The ID of the Service Point where this request can be picked up
pickupServicePoint	object	The full object of the Service Point record from pickupServicePointId
tags	object	Tags
metadata	object	Metadata about creation and changes to requests, provided by the server (client should not provide)
requestProcessingParameters	object	Additional parameters used for request processing and discarded afterwards. Not part of request record.
searchIndex	object	Request fields used for search
batchRequestInfo	object	Information about the batch request this request is part of

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/folio/main/json-schema/folio-request-schema.json",
  "title": "request",
  "description": "Request for an item that might be at a different location or already checked out to another patron",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/folio-mod-circulation-bff-circulationbff-openapi.yml#/components/schemas/request",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of the request",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "requestType": {
      "description": "Whether the item should be held upon return, recalled or paged for",
      "type": "string",
      "enum": [
        "Hold",
        "Recall",
        "Page"
      ]
    },
    "requestLevel": {
      "description": "Level of the request - Item or Title",
      "type": "string",
      "enum": [
        "Item",
        "Title"
      ]
    },
    "ecsRequestPhase": {
      "description": "Stage in ECS request process, absence of this field means this is a single-tenant request",
      "type": "string",
      "enum": [
        "Primary",
        "Secondary"
      ]
    },
    "requestDate": {
      "description": "Date the request was made",
      "type": "string",
      "format": "date-time"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    },
    "requesterId": {
      "description": "ID of the user who made the request",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "instanceId": {
      "description": "ID of the instance being requested",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "holdingsRecordId": {
      "description": "ID of the holdings record being requested",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "itemId": {
      "description": "ID of the item being requested",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "status": {
      "description": "Status of the request",
      "type": "string",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Open - Awaiting delivery",
        "Closed - Filled",
        "Closed - Cancelled",
        "Closed - Unfilled",
        "Closed - Pickup expired"
      ]
    },
    "cancellationReasonId": {
      "description": "The id of the request reason",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "cancelledByUserId": {
      "description": "The id of the user that cancelled the request",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancellation",
      "type": "string"
    },
    "cancelledDate": {
      "description": "Date the request was cancelled",
      "type": "string",
      "format": "date-time"
    },
    "position": {
      "description": "position of the request in a per-item request queue",
      "type": "integer",
      "minimum": 1
    },
    "instance": {
      "description": "Copy of some instance metadata (used for searching and sorting)",
      "type": "object",
      "properties": {
        "title": {
          "description": "title of the item",
          "type": "string"
        },
        "identifiers": {
          "type": "array",
          "description": "An extensible set of name-value pairs of identifiers associated with the resource",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "description": "Resource identifier value"
              },
              "identifierTypeId": {
                "type": "string",
                "description": "UUID of resource identifier type (e.g. ISBN, ISSN, LCCN, CODEN, Locally defined identifiers)",
                "$ref": "#/$defs/uuid"
              }
            },
            "required": [
              "value",
              "identifierTypeId"
            ]
          }
        }
      },
      "additionalProperties": true
    },
    "item": {
      "description": "Copy of some item metadata (used for searching and sorting)",
      "type": "object",
      "properties": {
        "barcode": {
          "description": "barcode of the item",
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "requester": {
      "description": "Copy of some requesting patron metadata (used for searching and sorting), will be taken from the user referred to by the requesterId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patron group that this user belongs to",
          "type": "string",
          "readonly": true,
          "$ref": "#/$defs/uuid"
        },
        "patronGroup": {
          "type": "object",
          "description": "record for the user's patrongroup",
          "$ref": "#/$defs/patronGroup"
        }
      },
      "additionalProperties": true
    },
    "proxy": {
      "description": "Copy of some proxy patron metadata (used for searching and sorting), will be taken from the user referred to by the proxyUserId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patrongroup that this user belongs to",
          "type": "string",
          "readonly": true,
          "$ref": "#/$defs/uuid"
        },
        "patronGroup": {
          "description": "record for the user's patrongroup",
          "type": "object",
          "readonly": true,
          "properties": {
            "id": {
              "description": "ID of the patrongroup",
              "type": "string",
              "readonly": true,
              "$ref": "#/$defs/uuid"
            },
            "group": {
              "description": "The unique name of the patrongroup",
              "type": "string",
              "readonly": true
            },
            "desc": {
              "description": "A description of the patrongroup",
              "type": "string",
              "readonly": true
            }
          }
        }
      }
    },
    "fulfillmentPreference": {
      "description": "How should the request be fulfilled (whether the item should be kept on the hold shelf for collection or delivered to the requester)",
      "type": "string",
      "enum": [
        "Hold Shelf",
        "Delivery"
      ]
    },
    "deliveryAddressTypeId": {
      "description": "Deliver to the address of this type, for the requesting patron",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "deliveryAddress": {
      "description": "Address the item is to be delivered to (derived from requester information)",
      "type": "object",
      "readonly": true,
      "properties": {
        "addressLine1": {
          "description": "Address line 1",
          "type": "string",
          "readonly": true
        },
        "addressLine2": {
          "description": "Address line 2",
          "type": "string",
          "readonly": true
        },
        "city": {
          "description": "City name",
          "type": "string",
          "readonly": true
        },
        "region": {
          "description": "Region",
          "type": "string",
          "readonly": true
        },
        "postalCode": {
          "description": "Postal code",
          "type": "string",
          "readonly": true
        },
        "countryId": {
          "description": "Country code",
          "type": "string",
          "readonly": true
        },
        "addressTypeId": {
          "description": "Type of address (refers to address types)",
          "type": "string",
          "readonly": true,
          "$ref": "#/$defs/uuid"
        }
      }
    },
    "requestExpirationDate": {
      "description": "Date when the request expires",
      "type": "string",
      "format": "date-time"
    },
    "holdShelfExpirationDate": {
      "description": "Date when an item returned to the hold shelf expires",
      "type": "string",
      "format": "date-time"
    },
    "pickupServicePointId": {
      "description": "The ID of the Service Point where this request can be picked up",
      "type": "string",
      "$ref": "#/$defs/uuid"
    },
    "pickupServicePoint": {
      "description": "The full object of the Service Point record from pickupServicePointId",
      "readonly": true,
      "properties": {
        "name": {
          "description": "Unique name for the service point",
          "type": "string",
          "readonly": true
        },
        "code": {
          "description": "Unique code for the service point",
          "type": "string",
          "readonly": true
        },
        "discoveryDisplayName": {
          "description": "Human-readable name for the service point",
          "type": "string",
          "readonly": true
        },
        "description": {
          "description": "Description of the service point",
          "type": "string",
          "readonly": true
        },
        "shelvingLagTime": {
          "description": "Shelving lag time",
          "type": "integer",
          "readonly": true
        },
        "pickupLocation": {
          "description": "Is this service point a pickup location?",
          "type": "boolean",
          "readonly": true
        }
      }
    },
    "tags": {
      "type": "object",
      "description": "Tags",
      "$ref": "#/$defs/uuid"
    },
    "metadata": {
      "description": "Metadata about creation and changes to requests, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "#/$defs/metadata"
    },
    "requestProcessingParameters": {
      "type": "object",
      "description": "Additional parameters used for request processing and discarded afterwards. Not part of request record.",
      "properties": {
        "overrideBlocks": {
          "type": "object",
          "description": "Blocks to override if user has corresponding permissions",
          "$ref": "#/$defs/overrideBlocks"
        }
      }
    },
    "searchIndex": {
      "description": "Request fields used for search",
      "type": "object",
      "$ref": "#/$defs/requestSearchIndex"
    },
    "batchRequestInfo": {
      "description": "Information about the batch request this request is part of",
      "type": "object",
      "properties": {
        "batchRequestId": {
          "description": "ID of the batch request",
          "type": "string",
          "$ref": "#/$defs/uuid"
        },
        "batchRequestSubmittedAt": {
          "description": "Date and time when the batch request was submitted",
          "type": "string",
          "format": "date-time"
        }
      },
      "additionalProperties": false,
      "required": [
        "batchRequestId",
        "batchRequestSubmittedAt"
      ]
    }
  },
  "required": [
    "requesterId",
    "requestType",
    "requestDate",
    "fulfillmentPreference"
  ],
  "$defs": {
    "metadata": {
      "type": "object",
      "description": "Record metadata",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      }
    },
    "overrideBlocks": {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "description": "Blocks to override (e.g. during checkout or renewal)",
      "properties": {
        "itemNotLoanableBlock": {
          "description": "'Item not loanable' block",
          "type": "object",
          "properties": {
            "dueDate": {
              "description": "Due date for a new loan",
              "type": "string",
              "format": "date-time"
            }
          },
          "additionalProperties": false,
          "required": [
            "dueDate"
          ]
        },
        "patronBlock": {
          "description": "Automated patron block",
          "type": "object",
          "additionalProperties": false
        },
        "itemLimitBlock": {
          "description": "Item limit block",
          "type": "object",
          "additionalProperties": false
        },
        "renewalBlock": {
          "description": "Renewal block",
          "type": "object",
          "additionalProperties": false
        },
        "renewalDueDateRequiredBlock": {
          "description": "Override renewal block which requires due date field",
          "type": "object",
          "properties": {
            "dueDate": {
              "description": "Due date for a new loan",
              "type": "string",
              "format": "date-time"
            }
          },
          "additionalProperties": false,
          "required": [
            "dueDate"
          ]
        },
        "comment": {
          "description": "Reason for override",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "patronGroup": {
      "description": "patron group",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the patron group",
          "type": "string",
          "$ref": "#/$defs/uuid"
        },
        "group": {
          "description": "The unique name of the patron group",
          "type": "string"
        },
        "desc": {
          "description": "A description of the patron group",
          "type": "string"
        }
      }
    },
    "requestSearchIndex": {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "description": "Request fields used for search",
      "type": "object",
      "properties": {
        "callNumberComponents": {
          "type": "object",
          "description": "Effective call number components",
          "properties": {
            "callNumber": {
              "type": "string",
              "description": "Effective Call Number is an identifier assigned to an item or its holding and associated with the item."
            },
            "prefix": {
              "type": "string",
              "description": "Effective Call Number Prefix is the prefix of the identifier assigned to an item or its holding and associated with the item."
            },
            "suffix": {
              "type": "string",
              "description": "Effective Call Number Suffix is the suffix of the identifier assigned to an item or its holding and associated with the item."
            }
          },
          "additionalProperties": false
        },
        "shelvingOrder": {
          "type": "string",
          "description": "A system generated normalization of the call number that allows for call number sorting in reports and search results"
        },
        "pickupServicePointName": {
          "description": "The name of the request pickup service point",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "uuid": {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this

find_json_schemasBrowse and filter every JSON Schema in the catalog.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This JSON Schema

curl "https://apis.io/api/v1/json-schemas/folio-request"

All schemas

curl "https://apis.io/api/v1/json-schemas?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.