FOLIO Get Inventory Items By Query API

openapi: 3.2.0
info:
  title: Folio Get Inventory Items By Query API
  version: v1
  description: 'Operations tagged getInventoryItemsByQuery across 2 of this provider''s published API definitions: folio-mod-circulation-bff-circulationbff-openapi.json, folio-mod-circulation-bff-circulationbff-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: getInventoryItemsByQuery
paths:
  /circulation-bff/inventory/items:
    get:
      description: Find items in mod-search by query and fetch item info from inventory
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      tags:
      - getInventoryItemsByQuery
      responses:
        '200':
          description: Inventory items by query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventoryItems'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Get circulation bff inventory items
      x-summary-source: derived
      operationId: getCirculationBffInventoryItems
      x-operation-id-source: derived
components:
  parameters:
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        description: Skip over a number of elements by specifying an offset value for the query
        default: 0
        example: 0
        minimum: 0
        maximum: 2147483647
    query:
      name: query
      in: query
      required: true
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        description: "Limit the number of elements returned in the response.\nUsing limit=0 will return totalRecords with the exact value.\nFor details about totalRecords see:\n  - https://github.com/folio-org/raml-module-builder#estimated-totalrecords\n"
        default: 10
        example: 10
        minimum: 0
        maximum: 2147483647
  schemas:
    parameter:
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      example:
        key: source
        value: 'null'
    errorResponse:
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/error'
        total_records:
          description: Total number of errors
          type: integer
      example:
        errors:
        - message: Illegal argument error
          type: IllegalArgumentException
          code: unknown_error
        total_records: 1
    inventoryItemNotes:
      $schema: http://json-schema.org/draft-04/schema#
      description: Note for item record
      type: object
      additionalProperties: true
      properties:
        itemNoteTypeId:
          description: Item note type, refers to a item-note-type reference record
          type: string
        note:
          description: Text to display (e.g. action note, binding, use and reproduction)
          type: string
        staffOnly:
          description: Records the fact that the record should only be displayed for staff
          type: boolean
          default: false
    tags:
      title: tags
      description: List of simple tags that can be added to an object
      type: object
      properties:
        tagList:
          description: List of tags
          type: array
          items:
            type: string
    inventoryItem:
      $schema: http://json-schema.org/draft-04/schema#
      description: An item record
      type: object
      properties:
        id:
          description: Item id
          type: string
        _version:
          type: integer
          description: Record version for optimistic locking
        hrid:
          type: string
          description: The human readable ID, also called eye readable ID. A system-assigned sequential alternate ID
        holdingsRecordId:
          description: ID of the holdings record the item is a member of
          type: string
        formerIds:
          type: array
          description: Previous identifiers assigned to the item
          items:
            type: string
          uniqueItems: true
        discoverySuppress:
          type: boolean
          description: Records the fact that the record should not be displayed in items.jsona discovery system
        displaySummary:
          description: Display summary about the item
          type: string
        title:
          type: string
          description: Resouce title (read only, inherited from associated instance record)
          readonly: true
        contributorNames:
          description: A list of contributor names
          type: array
          items:
            type: object
            properties:
              name:
                description: The contributor name
                type: string
        callNumber:
          type: string
          description: Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record)
          readonly: true
        barcode:
          description: Text, with input likely validated by the barcode scanner
          type: string
        effectiveShelvingOrder:
          type: string
          description: A system generated normalization of the call number that allows for call number sorting in reports and search results
          readonly: true
        accessionNumber:
          type: string
          description: Accession number is also called inventar number. Accession number is a unique number assigned to an item in the order in which it is added to a library collection. Most libraries assign accession numbers in continous numerical sequece, but some use a code system to indicate type of material and/or year of accession in addition to order of accession
        itemLevelCallNumber:
          description: Call number is an identifier assigned to an item, usually printed on a label attached to the item, and used to determine its physical position in a shelving sequence (e.g. K1 .M44, read only, inherited from associated holdings record). The item level call number, is the call number on item level
          type: string
        itemLevelCallNumberPrefix:
          description: Prefix of the call number on the item level
          type: string
        itemLevelCallNumberSuffix:
          description: Suffix of the call number on the item level
          type: string
        itemLevelCallNumberTypeId:
          description: Call number type, refers to a call-number-type reference record
          type: string
        effectiveCallNumberComponents:
          type: object
          description: Elements of a full call number generated from the item or holding
          properties:
            callNumber:
              type: string
              description: Effective Call Number is an identifier assigned to an item or its holding and associated with the item.
              readonly: true
            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.
              readonly: true
            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.
              readonly: true
            typeId:
              type: string
              description: Effective Call Number Type Id is the call number type id assigned to the item or associated holding.
              $ref: '#/components/schemas/uuid'
              readonly: true
        volume:
          description: Volume is intended for monographs when a multipart monograph (e.g. a biography of Gerorge Bernard Shaw in three volumes)
          type: string
        enumeration:
          description: Enumeration is the descriptive information for the numbering scheme of a serial, usually identified by level and a descriptive caption, e.g., level 0 = v. and level 1 = no. This means that each issue of the serial has a volume and an issue number that would appear (e.g. v.71:no.6-2)
          type: string
        chronology:
          description: Chronology is the descriptive information for the dating scheme of a serial, usually identified by level, e.g., level 0 = year level 1 = month. This means that each issue of the serial has a month and a year on each issue (e.g. 1985:July-Dec.)
          type: string
        yearCaption:
          description: In multipart monographs, a caption is characters used to label a level of chronology (e.g. 'year 1985')
          type: array
          items:
            type: string
          uniqueItems: true
        itemIdentifier:
          description: Item identifier number, e.g. imported from the union catalogue (read only)
          type: string
        copyNumber:
          description: Copy number is the piece identifier. The copy number reflects if the library has a copy of a single-volume monograph; a copy of a multi-volume, (e.g. Copy 1, or C.7.)
          type: string
        numberOfPieces:
          description: Number of pieces. Used when an item is checked out or returned to verify that all parts are present (e.g. 7 CDs in a set)
          type: string
        descriptionOfPieces:
          description: Text which descripe the pieces
          type: string
        numberOfMissingPieces:
          description: Number of missing pieces
          type: string
        missingPieces:
          description: Text which descripes the missing pieces
          type: string
        missingPiecesDate:
          description: Date when the piece(s) went missing
          type: string
        itemDamagedStatusId:
          description: Item Damage status Id, refers to an Item damage Status ID reference record
          type: string
        itemDamagedStatusDate:
          description: Date when damage status was last changed
          type: string
        administrativeNotes:
          type: array
          description: Administrative notes
          minItems: 0
          items:
            type: string
        notes:
          description: notes
          type: array
          items:
            $ref: '#/components/schemas/inventoryItemNotes'
        circulationNotes:
          type: array
          description: Notes to be displayed in circulation processes
          items:
            type: object
            properties:
              noteType:
                type: string
                description: Type of circulation process that the note applies to
                enum:
                - Check in
                - Check out
              note:
                type: string
                description: Text to display
              staffOnly:
                type: boolean
                description: Records the fact that the note should only be displayed for staff
                default: false
              source:
                type: object
                description: The user who added/updated the note. The property is generated by the server and needed to support sorting.
                readonly: true
                properties:
                  id:
                    type: string
                    description: The id of the user who added/updated the note
                    readonly: true
                  personal:
                    type: object
                    description: Personal information about the user
                    readonly: true
                    properties:
                      lastName:
                        type: string
                        description: The user's last name
                        readonly: true
                      firstName:
                        type: string
                        description: The user's first name
                        readonly: true
              date:
                type: string
                description: Date and time the record is added/updated. The property is generated by the server and needed to support sorting.
                readonly: true
            additionalProperties: true
        status:
          description: The status of the item
          type: object
          properties:
            name:
              description: 'Name of the item state (e.g. Available, Checked out, In transit, Awaiting pickup, On order). Default value is set to: Available'
              type: string
              enum:
              - Aged to lost
              - Available
              - Awaiting delivery
              - Awaiting pickup
              - Checked out
              - Claimed returned
              - Declared lost
              - Lost and paid
              - Long missing
              - Missing
              - In process
              - In process (non-requestable)
              - In transit
              - Intellectual item
              - On order
              - Order closed
              - Paged
              - Restricted
              - Unavailable
              - Unknown
              - Withdrawn
            date:
              description: Date of the current item state. E.g. date set when item state was changed by the Check out app
              type: string
              readonly: true
              format: date-time
          additionalProperties: true
          required:
          - name
        materialType:
          description: Material type define what type of thing the item is
          type: object
          properties:
            id:
              description: Material type Id, refers to a material type reference record
              type: string
            name:
              description: 'Material type name (e.g. Audio book, Audio disc, Computer file, Pamphelet) '
              type: string
          additionalProperties: true
          required:
          - id
        isBoundWith:
          description: Indicates if this Item is a bound-with
          type: boolean
          default: false
          readonly: true
        boundWithTitles:
          description: List of titles that are bound together within this Item
          type: array
          items:
            type: object
            description: A title that is bound with other titles within this Item
            properties:
              briefHoldingsRecord:
                type: object
                description: Information about a holdings record that links a title to the bound-with Item
                properties:
                  id:
                    description: The UUID of the holdingsRecord
                    type: string
                  hrid:
                    description: The human-readable ID of the holdingsRecord
                    type: string
                additionalProperties: true
              briefInstance:
                type: object
                description: Information about an Instance / title that is bound with other title within this Item
                properties:
                  id:
                    description: The UUID of the Instance
                    type: string
                  hrid:
                    description: The human-readable ID of the Instance
                    type: string
                  title:
                    description: The title of the Instance
                    type: string
                additionalProperties: true
            additionalProperties: true
          readonly: true
        permanentLoanType:
          description: Permanent loan type, is the default loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)
          type: object
          properties:
            id:
              description: Permanent loan type Id, refers to a loan type reference record
              type: string
            name:
              description: Permanent loan type name
              type: string
          additionalProperties: true
          required:
          - id
        temporaryLoanType:
          description: Temporary loan type, is the temporary loan type for a given item. Loan types are tenant-defined in a reference table in Settings, Inventory, Item, Loan type (e.g. Can circulate, Course reserves, Reading room, Selected)
          type: object
          properties:
            id:
              description: Temporary loan type Id, refers to a loan type reference record
              type: string
            name:
              description: Temporary loan type name
              type: string
          additionalProperties: true
          required:
          - id
        permanentLocation:
          description: Permanent item location is the default location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed
          type: object
          properties:
            id:
              description: Permanent location Id, refers to a location type reference record
              type: string
            name:
              description: Permanent location type name
              type: string
          additionalProperties: true
          required:
          - id
        temporaryLocation:
          description: Temporary item location is the temporarily location, shelving location, or holding which is a physical place where items are stored, or an Online location. The location is defined by Institutions, Campuses, libraries, and locations. Permanent location can be assigned at the holding level, and be overridden at the item level if needed
          type: object
          properties:
            id:
              description: Temporary location Id, refers to a location type reference record
              type: string
            name:
              description: Temporary location name
              type: string
          additionalProperties: true
          required:
          - id
        effectiveLocation:
          type: object
          description: The effective location is used by FOLIO and other integrated systems to know the current home location for the item (read only, derived from locations on HoldingsRecord and Item)
          readonly: true
          properties:
            id:
              type: string
              readonly: true
            name:
              description: Effective location name
              type: string
              readonly: true
        electronicAccess:
          description: Whether an item is available electronically
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
                description: Uniform Resource Identifier (URI) is a string of characters designed for unambiguous identification of resources
              linkText:
                type: string
                description: Link text is used for display in place of the URL
              materialsSpecification:
                type: string
                description: Materials specified is used to specify to what portion or aspect of the resource the electronic location and access information applies (e.g. a portion or subset of the item is electronic, or a related electronic resource is being linked to the record)
              publicNote:
                type: string
                description: URL public note to be displayed in the discovery
              relationshipId:
                type: string
                description: 'Relationship Id, refers to a Relationship type reference record. Relationship between the electronic resource at the location identified and the item described in the record as a whole. (E.g. values from MARC 21, tag field 856 2nd indicator, where the values are: No information provided, Resource, Version of resource, Related resource, No display constant generate'
            additionalProperties: true
            required:
            - uri
        inTransitDestinationServicePointId:
          description: Service point an item is intended to be transited to (should only be present when in transit)
          type: string
          $ref: '#/components/schemas/uuid'
        statisticalCodeIds:
          type: array
          description: Statistical code Id, refers to a Statistical code reference record
          items:
            type: string
          uniqueItems: true
        purchaseOrderLineIdentifier:
          type: string
          description: ID referencing a remote purchase order object related to this item
        metadata:
          description: Metadata about creation and changes, provided by the server (client should not provide)
          type: object
          $ref: '#/components/schemas/metadata'
          readonly: true
        tags:
          description: arbitrary tags associated with this item
          id: tags
          type: object
          $ref: '#/components/schemas/tags'
        lastCheckIn:
          type: object
          additionalProperties: true
          description: Information about when an item was last checked in
          properties:
            dateTime:
              type: string
              description: Date and time of the last check in of the item.
              format: date-time
              readonly: true
            servicePointId:
              type: string
              description: Service point ID being used by a staff member when item was scanned in Check in app.
              $ref: '#/components/schemas/uuid'
              readonly: true
            staffMemberId:
              type: string
              description: ID a staff member who scanned the item
              $ref: '#/components/schemas/uuid'
              readonly: true
      additionalProperties: true
      required:
      - materialType
      - permanentLoanType
      - status
    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}$
    error:
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/parameter'
    inventoryItems:
      $schema: http://json-schema.org/draft-04/schema#
      description: A collection of item records
      type: object
      properties:
        items:
          description: List of item records
          id: items
          type: array
          items:
            type: object
            $ref: '#/components/schemas/inventoryItem'
        totalRecords:
          type: integer
      additionalProperties: true
      required:
      - items
      - totalRecords
    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
  examples:
    validationErrorResponse:
      value:
        errors:
        - message: must not be null
          type: MethodArgumentNotValidException
          code: validation_error
          parameters:
          - key: parameter
            value: 'null'
        total_records: 1
    unknownError:
      value:
        errors:
        - message: Illegal argument error
          type: IllegalArgumentException
          code: unknown_error
        total_records: 1
  responses:
    internalServerErrorResponse:
      description: When unhandled exception occurred during code execution, e.g. NullPointerException.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            unknownError:
              $ref: '#/components/examples/unknownError'
    unprocessableEntityResponse:
      description: Validation error for the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            response:
              $ref: '#/components/examples/validationErrorResponse'
    badRequestResponse:
      description: Validation errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            validationErrorResponse:
              $ref: '#/components/examples/validationErrorResponse'
x-refined-from:
- folio-mod-circulation-bff-circulationbff-openapi.json
- folio-mod-circulation-bff-circulationbff-openapi.yml