edge-patron.raml

#%RAML 1.0
title: Patron Services
baseUri: https://github.com/folio-org/mod-patron
protocols: [ HTTPS ]
version: v4.4

documentation:
  - title: Patron Services
    content: |
      This module allows 3rd party discovery services to perform patron
      actions in FOLIO

types:
  account: !include account.json
  hold: !include hold.json
  loan: !include loan.json
  charge: !include charge.json
  money: !include money.json
  item: !include item.json
  external_patron: !include external_patron.json
  staging_user: !include staging_user.json
  user: !include userdata.json
  external_patron_collection: !include external_patron_collection.json
  allowedServicePoints: !include allowed-service-points-response.json
  allowedServicePointsMultiItemRequest: !include multi-item-allowed-service-points-request.json
  allowedServicePointsMultiItemResponse: !include multi-item-allowed-service-points-response.json
  batchRequest: !include batch-request.json
  batchRequestSubmitResult: !include batch-request-response.json
  batchRequestStatus: !include batch-request-status-response.json
  hold-cancellation: !include hold-cancellation.json
  errors: !include raml-util/schemas/errors.schema
  external_patron_error_404: !include schemas/external_patron_error_404.schema
  staging_user_error_404: !include schemas/staging_user_error_404.schema
  external_patron_error_get_422: !include schemas/external_patron_error_get_422.schema
  external_patron_error_post_422: !include schemas/external_patron_error_post_422.schema
  external_patron_error_put_422: !include schemas/external_patron_error_put_422.schema
  user_error_400: !include schemas/user_error_400.schema
  user_error_404: !include schemas/user_error_404.schema

/patron:
  displayName: Patron Services
  description: |
    Services that allow patron empowerment from 3rd party discovery services
  post:
    description: |
      Create a staging user or update a staging user if it exists
    queryParameters:
      apikey:
        description: "API Key"
        type: string
    body:
      application/json:
        type: staging_user
        example: !include examples/staging_user.json
    responses:
      200:
        description: |
          staging user updated successfully
        body:
          application/json:
            type: staging_user
            example: !include examples/staging_user.json
      201:
        description: |
          staging user created successfully
        body:
          application/json:
            type: staging_user
            example: !include examples/staging_user.json
      400:
        description: Bad request
        body:
          text/plain:
            example: unable to process request
      401:
        description: Not authorized to perform requested action
        body:
          text/plain:
            example: unable to create request
      403:
        description: Access Denied
        body:
          text/plain:
            example: Access Denied
      422:
        description: Validation error
        body:
          text/plain:
            example: Validation error
      500:
        description: |
          Internal server error, e.g. due to misconfiguration
        body:
          text/plain:
            example: internal server error, contact administrator

  /{externalSystemId}:
    uriParameters:
      externalSystemId:
        description: The UUID of a staging user
        type: string
        pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
    put:
      description: |
        Update a staging user based on external system ID.
      queryParameters:
        apikey:
          description: "API Key"
          type: string
      body:
        application/json:
          type: staging_user
          example: !include examples/staging_user.json
      responses:
        200:
          description: |
            staging user updated successfully
          body:
            application/json:
              type: staging_user
              example: !include examples/staging_user.json
        400:
          description: Bad request
          body:
            text/plain:
              example: unable to process request
        401:
          description: Not authorized to perform requested action
          body:
            text/plain:
              example: unable to create request
        403:
          description: Access Denied
          body:
            text/plain:
              example: Access Denied
        422:
          description: Validation error
          body:
            text/plain:
              example: Validation error
        500:
          description: |
            Internal server error, e.g. due to misconfiguration
          body:
            text/plain:
              example: internal server error, contact administrator
        404:
          description: Staging user with a given external system Id not found
          body:
            application/json:
              type: staging_user_error_404
              example: !include examples/staging_user_error.json


  /account:
    post:
      description: |
        Creates external patron request
      queryParameters:
        apikey:
          description: "API Key"
          type: string
      body:
        application/json:
          type: external_patron
          example: !include examples/external_patron.json
      responses:
        201:
          description: |
            Returns data for a new created external patron
          body:
            application/json:
              type: external_patron
              example: !include examples/external_patron.json
        400:
          description: Bad request
          body:
            text/plain:
              example: unable to process request
        401:
          description: Not authorized to perform requested action
          body:
            text/plain:
              example: unable to create request
        403:
          description: Access Denied
          body:
            text/plain:
              example: Access Denied
        409:
          description: Conflict
          body:
            text/plain:
              example: Optimistic Locking Conflict
        422:
          description: Validation error
          body:
            application/json:
              type: external_patron_error_post_422
              example: !include examples/external_patron_error.json
        500:
          description: |
            Internal server error, e.g. due to misconfiguration
          body:
            text/plain:
              example: internal server error, contact administrator
    get:
      description: (Secure) Return account details for the user provided in access token(x-okapi-token)
      queryParameters:
        includeLoans:
          description: |
            Indicates whether or not to include the loans array in
            the response
          required: false
          type: boolean
          default: false
        includeCharges:
          description: |
            Indicates whether or not to include the charges array in
            the response
          required: false
          type: boolean
          default: false
        includeHolds:
          description: |
            Indicates whether or not to include the holds array in
            the response
          required: false
          type: boolean
          default: false
        includeBatches:
          description: |
            Indicates whether or not to include the batch requests info in
            the response
          required: false
          type: boolean
          default: false
        apikey:
          description: "API Key"
          type: string
        sortBy:
          description: |
            Part of CQL query, indicates the order of records within the lists of holds, charges, loans
          example: item.title/sort.ascending
          required: false
          type: string
        offset:
          description: |
            Skip over a number of elements by specifying an offset value for the query
          type: integer
          required: false
          example: 1
          minimum: 0
          maximum: 2147483647
        limit:
          description: |
            Limit the number of elements returned in the response
          type: integer
          required: false
          example: 10
          minimum: 0
          maximum: 2147483647
      responses:
        200:
          description: Returns the user account info
          body:
            application/json:
              type: account
              example: !include examples/account.json
        400:
          description: Bad request
          body:
            text/plain:
              example: unable to process request -- constraint violation
        401:
          description: Not authorized to perform requested action
          body:
            text/plain:
              example: unable to get account -- unauthorized
        404:
          description: Item with a given ID not found
          body:
            text/plain:
              example: account not found
        403:
          description: Access Denied
          body:
            text/plain:
              example: Access Denied
        500:
          description: Internal server error, e.g. due to misconfiguration
          body:
            text/plain:
              example: internal server error, contact administrator
    /item:
      /{itemId}:
        uriParameters:
          itemId:
            description: The UUID of a FOLIO item
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
        /hold:
          displayName: Hold Management
          description: (Secure) Services that provide hold management
          post:
            description: |
              (Secure) Creates a hold request on an existing item for the user
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: hold
                example: !include examples/hold.json
            responses:
              201:
                description: |
                  Returns data for a new hold request on the specified item
                body:
                  application/json:
                    type: hold
                    example: !include examples/hold.json
              400:
                description: Bad request
                body:
                  text/plain:
                    example: unable to process request -- constraint violation
              401:
                description: Not authorized to perform requested action
                body:
                  text/plain:
                    example: unable to create hold -- unauthorized
              404:
                description: Item with a given ID not found
                body:
                  text/plain:
                    example: item not found
              403:
                description: Access Denied
                body:
                  text/plain:
                    example: Access Denied
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
        /allowed-service-points:
          displayName: Allowed service points
          description: Service that provides a list of allowed pickup service points
          get:
            description: |
              (Secure) Returns a list of pickup service points allowed for a particular patron and instance
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: allowedServicePoints
                example: !include examples/allowed-service-points-response.json
            responses:
              200:
                description: |
                  Successfully returns a list of allowed service points
                body:
                  application/json:
                    type: allowedServicePoints
                    example: !include examples/allowed-service-points-response.json
              422:
                description: Validation error
                body:
                  application/json:
                    type: errors
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
    /instance:
      /{instanceId}:
        uriParameters:
          instanceId:
            description: The UUID of a FOLIO instance
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
        /hold:
          displayName: Hold Management
          description: Services that provide hold management
          post:
            description: |
              (Secure) Creates a hold request on an existing item by instance ID for the user
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: hold
                example: !include examples/hold.json
            responses:
              201:
                description: |
                  Returns data for a new hold request on the selected item
                body:
                  application/json:
                    type: hold
                    example: !include examples/hold.json
              400:
                description: Bad request
                body:
                  text/plain:
                    example: unable to process request -- constraint violation
              401:
                description: Not authorized to perform requested action
                body:
                  text/plain:
                    example: unable to create hold -- unauthorized
              404:
                description: Instance with a given ID not found
                body:
                  text/plain:
                    example: item not found
              403:
                description: Access Denied
                body:
                  text/plain:
                    example: Access Denied
              422:
                description: Validation error
                body:
                  application/json:
                    type : errors
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
        /allowed-service-points:
          displayName: Allowed service points
          description: Service that provides a list of allowed pickup service points
          get:
            description: |
              (Secure) Returns a list of pickup service points allowed for a particular patron and instance
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: allowedServicePoints
                example: !include examples/allowed-service-points-response.json
            responses:
              200:
                description: |
                  Successfully returns a list of allowed service points
                body:
                  application/json:
                    type: allowedServicePoints
                    example: !include examples/allowed-service-points-response.json
              422:
                description: Validation error
                body:
                  application/json:
                    type: errors
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
        /allowed-service-points-multi-item:
          displayName: Allowed service points for multiple items
          description: Service that provides a list of allowed pickup service points for multiple items
          post:
            description: |
              (Secure) For a particular patron returns a list of allowed pickup service points per item
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: allowedServicePointsMultiItemRequest
                example: !include examples/multi-item-allowed-service-points-request.json
            responses:
              200:
                description: |
                  Successfully returns a list of allowed service points per item
                body:
                  application/json:
                    type: allowedServicePointsMultiItemResponse
                    example: !include examples/multi-item-allowed-service-points-response.json
              422:
                description: Validation error
                body:
                  application/json:
                    type: errors
              500:
                description: |

        /batch-request:
          displayName: Multi-Item Request
          description: Services that provide multi-item request management
          post:
            description: |
              (Secure) Submits a batch multi-item request for a particular patron and instance's items
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: batchRequest
                example: !include examples/batch-request.json
            responses:
              200:
                description: |
                  Returns multi-item request submission result
                body:
                  application/json:
                    type: batchRequestSubmitResult
                    example: !include examples/batch-request-response.json
              400:
                description: Bad request
                body:
                  text/plain:
                    example: |
                      unable to process request -- constraint violation
              422:
                description: Validation error
                body:
                  application/json:
                    type: errors
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
          /{batchRequestId}:
            uriParameters:
              batchRequestId:
                description: The UUID of a batch request
                type: string
                pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
            /status:
              get:
                description: |
                  (Secure) Returns the status of a batch multi-item request
                queryParameters:
                  apikey:
                    description: "API Key"
                    type: string
                responses:
                  200:
                    description: |
                      Successfully returns the status of a batch request
                    body:
                      application/json:
                        type: batchRequestStatus
                        example: !include examples/batch-request-status-response.json
                  404:
                    description: Batch request with a given ID not found
                    body:
                      text/plain:
                        example: Multi-Item request not found
                  422:
                    description: Validation error
                    body:
                      application/json:
                        type: errors
                  500:
                    description: |
                      Internal server error, e.g. due to misconfiguration
                    body:
                      text/plain:
                        example: internal server error, contact administrator
    /hold:
      displayName: Hold Management
      description: Services that provide hold management
      /{holdId}:
        displayName: Hold Management By Id
        description: Services that provide hold management by Id
        uriParameters:
          holdId:
            description: The UUID of a FOLIO hold request
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
        /cancel:
          post:
            description: (Secure) Removes the specified hold request
            queryParameters:
              apikey:
                description: "API Key"
                type: string
            body:
              application/json:
                type: hold-cancellation
                example: !include examples/hold-cancellation.json
            responses:
              201:
                description: The specified hold request was removed
                body:
                  application/json:
                    type: hold
                    example: !include examples/hold.json
              400:
                description: Bad request
                body:
                  text/plain:
                    example: |
                      unable to process request -- constraint violation
              401:
                description: Not authorized to perform requested action
                body:
                  text/plain:
                    example: unable to cancel hold -- unauthorized
              404:
                description: hold with a given ID not found
                body:
                  text/plain:
                    example: hold not found
              403:
                description: Access denied
                body:
                  text/plain:
                    example: access denied
              500:
                description: |
                  Internal server error, e.g. due to misconfiguration
                body:
                  text/plain:
                    example: internal server error, contact administrator
    /external-patrons:
      displayName: Get Accounts of External Patrons
      description: Get accounts of external patrons based on flag
      get:
        description: Return external_patrons detail
        queryParameters:
          expired:
            description: Indicates to return only expired patron
            required: false
            type: boolean
            default: false
          apikey:
            description: "API Key"
            type: string
        responses:
          200:
            description: Returns the external patron accounts collection
            body:
              application/json:
                type: external_patron_collection
                example: !include examples/external_patron_collection.json
          400:
            description: Bad request
            body:
              text/plain:
                example: unable to process request -- constraint violation
          401:
            description: Not authorized to perform requested action
            body:
              text/plain:
                example: unable to get account -- unauthorized
          403:
            description: Access Denied
            body:
              text/plain:
                example: Access Denied
          500:
            description: Internal server error, e.g. due to misconfiguration
            body:
              text/plain:
                example: internal server error, contact administrator
    /by-email/{emailId}:
      displayName: Get Accounts By email
      description: Service endpoints that manage accounts by an existing email
      uriParameters:
        emailId:
          description: The email of external patron
          type: string
      get:
        description: Return account details for the specified external patron email
        queryParameters:
          apikey:
            description: "API Key"
            type: string
        responses:
          200:
            description: Returns the external patron account info
            body:
              application/json:
                type: external_patron
                example: !include examples/external_patron.json
          400:
            description: Bad request
            body:
              text/plain:
                example: unable to process request -- constraint violation
          401:
            description: Not authorized to perform requested action
            body:
              text/plain:
                example: unable to get account -- unauthorized
          404:
            description: Item with a given EMAIL not found
            body:
              application/json:
                type: external_patron_error_404
                example: !include examples/external_patron_error.json
          422:
            description: Validation error
            body:
              application/json:
                type: external_patron_error_get_422
                example: !include examples/external_patron_error.json
          403:
            description: Access Denied
            body:
              text/plain:
                example: Access Denied
          500:
            description: Internal server error, e.g. due to misconfiguration
            body:
              text/plain:
                example: internal server error, contact administrator
      put:
        description: Updates external patron request
        queryParameters:
          apikey:
            description: "API Key"
            type: string
        body:
          application/json:
            type: external_patron
            example: !include examples/external_patron.json
        responses:
          204:
            description: |
              Returns data for a updated external patron request
            body:
              application/json:
                type: external_patron
                example: !include examples/external_patron.json
          400:
            description: Bad request
            body:
              text/plain:
                example: unable to process request
          401:
            description: Not authorized to perform requested action
            body:
              text/plain:
                example: unable to create request
          404:
            description: Item with a given ID not found
            body:
              application/json:
                type: external_patron_error_404
                example: !include examples/external_patron_error.json
          403:
            description: Access Denied
            body:
              text/plain:
                example: Access Denied
          409:
            description: Conflict
            body:
              text/plain:
                example: Optimistic Locking Conflict
          422:
            description: Validation error
            body:
              application/json:
                type: external_patron_error_put_422
                example: !include examples/external_patron_error.json
          500:
            description: |
              Internal server error, e.g. due to misconfiguration
            body:
              text/plain:
                example: internal server error, contact administrator
    /{id}:
      displayName: Manage Accounts By Id
      description: Service endpoints that manage accounts by an existing Id
      uriParameters:
        id:
          description: Patron's external system Id stored in FOLIO user record.
          type: string
      get:
        description: Return account details for the specified FOLIO user id
        queryParameters:
          includeLoans:
            description: |
              Indicates whether or not to include the loans array in
              the response
            required: false
            type: boolean
            default: false
          includeCharges:
            description: |
              Indicates whether or not to include the charges array in
              the response
            required: false
            type: boolean
            default: false
          includeHolds:
            description: |
              Indicates whether or not to include the holds array in
              the response
            required: false
            type: boolean
            default: false
          includeBatches:
            description: |
              Indicates whether or not to include the batch requests info in
              the response
            required: false
            type: boolean
            default: false
          apikey:
            description: "API Key"
            type: string
          sortBy:
            description: |
              Part of CQL query, indicates the order of records within the lists of holds, charges, loans
            example: item.title/sort.ascending
            required: false
            type: string
          offset:
            description: |
              Skip over a number of elements by specifying an offset value for the query
            type: integer
            required: false
            example: 1
            minimum: 0
            maximum: 2147483647
          limit:
            description: |
              Limit the number of elements returned in the response
            type: integer
            required: false
            example: 10
            minimum: 0
            maximum: 2147483647
        responses:
          200:
            description: Returns the user account info
            body:
              application/json:
                type: account
                example: !include examples/account.json
          400:
            description: Bad request
            body:
              text/plain:
                example: unable to process request -- constraint violation
          401:
            description: Not authorized to perform requested action
            body:
              text/plain:
                example: unable to get account -- unauthorized
          404:
            description: Item with a given ID not found
            body:
              text/plain:
                example: account not found
          403:
            description: Access Denied
            body:
              text/plain:
                example: Access Denied
          500:
            description: Internal server error, e.g. due to misconfiguration
            body:
              text/plain:
                example: internal server error, contact administrator
      /item:
        /{itemId}:
          uriParameters:
            itemId:
              description: The UUID of a FOLIO item
              type: string
              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
          /renew:
            displayName: Renew a Loan
            description: Service endpoint for loan renewal
            post:
              description: Renews a loan on the item for the user
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              responses:
                201:
                  description: Returns the renewed loan data
                  body:
                    application/json:
                      type: loan
                      example: !include examples/loan.json
                400:
                  description: Bad request
                  body:
                    text/plain:
                      example: unable to process request -- constraint violation
                401:
                  description: Not authorized to perform requested action
                  body:
                    text/plain:
                      example: unable to renew loan -- unauthorized
                404:
                  description: Item with a given ID not found
                  body:
                    text/plain:
                      example: item not found
                403:
                  description: Access Denied
                  body:
                    text/plain:
                      example: Access Denied
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
          /hold:
            displayName: Hold Management
            description: Services that provide hold management
            post:
              description: |
                Creates a hold request on an existing item for the user
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: hold
                  example: !include examples/hold.json
              responses:
                201:
                  description: |
                    Returns data for a new hold request on the specified item
                  body:
                    application/json:
                      type: hold
                      example: !include examples/hold.json
                400:
                  description: Bad request
                  body:
                    text/plain:
                      example: unable to process request -- constraint violation
                401:
                  description: Not authorized to perform requested action
                  body:
                    text/plain:
                      example: unable to create hold -- unauthorized
                404:
                  description: Item with a given ID not found
                  body:
                    text/plain:
                      example: item not found
                403:
                  description: Access Denied
                  body:
                    text/plain:
                      example: Access Denied
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
          /allowed-service-points:
            displayName: Allowed service points
            description: Service that provides a list of allowed pickup service points
            get:
              description: |
                Returns a list of pickup service points allowed for a particular patron and instance
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: allowedServicePoints
                  example: !include examples/allowed-service-points-response.json
              responses:
                200:
                  description: |
                    Successfully returns a list of allowed service points
                  body:
                    application/json:
                      type: allowedServicePoints
                      example: !include examples/allowed-service-points-response.json
                422:
                  description: Validation error
                  body:
                    application/json:
                      type: errors
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
      /instance:
        /{instanceId}:
          uriParameters:
            instanceId:
              description: The UUID of a FOLIO instance
              type: string
              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
          /hold:
            displayName: Hold Management
            description: Services that provide hold management
            post:
              description: |
                Creates a hold request on an existing item by instance ID for the user
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: hold
                  example: !include examples/hold.json
              responses:
                201:
                  description: |
                    Returns data for a new hold request on the selected item
                  body:
                    application/json:
                      type: hold
                      example: !include examples/hold.json
                400:
                  description: Bad request
                  body:
                    text/plain:
                      example: unable to process request -- constraint violation
                401:
                  description: Not authorized to perform requested action
                  body:
                    text/plain:
                      example: unable to create hold -- unauthorized
                404:
                  description: Instance with a given ID not found
                  body:
                    text/plain:
                      example: item not found
                403:
                  description: Access Denied
                  body:
                    text/plain:
                      example: Access Denied
                422:
                  description: Validation error
                  body:
                    application/json:
                      type : errors
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
          /allowed-service-points:
            displayName: Allowed service points
            description: Service that provides a list of allowed pickup service points
            get:
              description: |
                Returns a list of pickup service points allowed for a particular patron and instance
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: allowedServicePoints
                  example: !include examples/allowed-service-points-response.json
              responses:
                200:
                  description: |
                    Successfully returns a list of allowed service points
                  body:
                    application/json:
                      type: allowedServicePoints
                      example: !include examples/allowed-service-points-response.json
                422:
                  description: Validation error
                  body:
                    application/json:
                      type: errors
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
          /allowed-service-points-multi-item:
            displayName: Allowed service points for multiple items
            description: Service that provides a list of allowed pickup service points for multiple items
            post:
              description: |
                For a particular patron returns a list of allowed pickup service points per item
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: allowedServicePointsMultiItemRequest
                  example: !include examples/multi-item-allowed-service-points-request.json
              responses:
                200:
                  description: |
                    Successfully returns a list of allowed service points per item
                  body:
                    application/json:
                      type: allowedServicePointsMultiItemResponse
                      example: !include examples/multi-item-allowed-service-points-response.json
                422:
                  description: Validation error
                  body:
                    application/json:
                      type: errors
                500:
                  description: |

          /batch-request:
            displayName: Multi-Item Request
            description: Services that provide multi-item request management
            post:
              description: |
                Submits a batch multi-item request for a particular patron and instance's items
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: batchRequest
                  example: !include examples/batch-request.json
              responses:
                200:
                  description: |
                    Returns multi-item request submission result
                  body:
                    application/json:
                      type: batchRequestSubmitResult
                      example: !include examples/batch-request-response.json
                400:
                  description: Bad request
                  body:
                    text/plain:
                      example: |
                        unable to process request -- constraint violation
                422:
                  description: Validation error
                  body:
                    application/json:
                      type: errors
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
            /{batchRequestId}:
              uriParameters:
                batchRequestId:
                  description: The UUID of a batch request
                  type: string
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
              /status:
                get:
                  description: |
                    Returns the status of a batch multi-item request
                  queryParameters:
                    apikey:
                      description: "API Key"
                      type: string
                  responses:
                    200:
                      description: |
                        Successfully returns the status of a batch request
                      body:
                        application/json:
                          type: batchRequestStatus
                          example: !include examples/batch-request-status-response.json
                    404:
                      description: Batch request with a given ID not found
                      body:
                        text/plain:
                          example: Multi-Item request not found
                    422:
                      description: Validation error
                      body:
                        application/json:
                          type: errors
                    500:
                      description: |
                        Internal server error, e.g. due to misconfiguration
                      body:
                        text/plain:
                          example: internal server error, contact administrator
      /hold:
        displayName: Hold Management
        description: Services that provide hold management
        /{holdId}:
          displayName: Hold Management By Id
          description: Services that provide hold management by Id
          uriParameters:
            holdId:
              description: The UUID of a FOLIO hold request
              type: string
              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
          /cancel:
            post:
              description: Removes the specified hold request
              queryParameters:
                apikey:
                  description: "API Key"
                  type: string
              body:
                application/json:
                  type: hold-cancellation
                  example: !include examples/hold-cancellation.json
              responses:
                201:
                  description: The specified hold request was removed
                  body:
                    application/json:
                      type: hold
                      example: !include examples/hold.json
                400:
                  description: Bad request
                  body:
                    text/plain:
                      example: |
                        unable to process request -- constraint violation
                401:
                  description: Not authorized to perform requested action
                  body:
                    text/plain:
                      example: unable to cancel hold -- unauthorized
                404:
                  description: hold with a given ID not found
                  body:
                    text/plain:
                      example: hold not found
                403:
                  description: Access denied
                  body:
                    text/plain:
                      example: access denied
                500:
                  description: |
                    Internal server error, e.g. due to misconfiguration
                  body:
                    text/plain:
                      example: internal server error, contact administrator
  /registration-status:
    get:
      description: Get the patron details by email ID or externalSystemId
      queryParameters:
        apikey:
          description: "API Key"
          type: string
        emailId:
          description: The email ID of the patron.
          type: string
        externalSystemId:
          description: The UUID of a staging user
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
      responses:
        200:
          description: patron information retrieved successfully
          body:
            application/json:
              type: user
              example: !include examples/user.json
        400:
          description: Validation error
          body:
            application/json:
              type: user_error_400
              example: !include examples/user_error.json
        401:
          description: Not authorized to perform requested action
          body:
            text/plain:
              example: unable to get account -- unauthorized
        403:
          description: Access Denied
          body:
            text/plain:
              example: Access Denied
        404:
          description: Validation error
          body:
            application/json:
              type: user_error_404
              example: !include examples/user_error.json
        500:
          description: Internal server error, e.g. due to misconfiguration
          body:
            text/plain:
              example: internal server error, contact administrator