Patron Services (v4.1)

https://github.com/folio-org/mod-patron

Table of contents

Patron Services

This module allows 3rd party discovery services to perform patron actions in FOLIO

Patron Services

Services that allow patron empowerment from 3rd party discovery services

GET /patron/account/{id}

Return account details for the specified FOLIO user id

GET /patron/account/{id}
URI Parameters
  • id: required (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}$)

    The UUID of a FOLIO user

Query Parameters
  • includeLoans: (boolean - default: false)

    Indicates whether or not to include the loans array in the response

  • includeCharges: (boolean - default: false)

    Indicates whether or not to include the charges array in the response

  • includeHolds: (boolean - default: false)

    Indicates whether or not to include the holds array in the response

Response 200

Returns the user account info

Body

Media type: application/json

Example:

{
  "totalCharges": {
    "amount": 50.0,
    "isoCurrencyCode": "USD"
  },
  "totalChargesCount": 1,
  "totalLoans": 1,
  "totalHolds": 1,
  "charges": [
    {
      "item" : {
        "instanceId" : "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
        "itemId" : "7d9dfe70-0158-489d-a7ed-2789eac277b3",
        "title" : "Some Book About Something",
        "author" : "Some Guy; Another Guy"
      },
      "chargeAmount" : {
        "amount" : 50.0,
        "isoCurrencyCode" : "USD"
      },
      "accrualDate" : "2018-01-31T00:00:01Z",
      "state" : "Paid Partially",
      "reason" : "damage - rebinding",
      "feeFineId" : "881c628b-e1c4-4711-b9d7-090af40f6a8f"
    }
  ],
  "holds": [
    {
      "requestId": "8bbac557-d66f-4571-bbbf-47a107cc1589",
      "item": {
        "instanceId": "255f82f3-5b1b-4239-93e4-ec6acf03ad9d",
        "itemId": "26670295-716a-4f84-8f65-2ef31707c017",
        "title": "I Want to Hold Your Hand",
        "author": "John Lennon; Paul McCartney"
      },
      "queuePosition": 1,
      "requestDate": "2018-06-02T08:16:30Z",
      "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
      "status": "Open - Not yet filled"
    }
  ],
  "loans": [
    {
      "id": "9a171a89-baca-4f1a-b2c4-d7253854864e",
      "item": {
        "instanceId": "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
        "itemId": "7d9dfe70-0158-489d-a7ed-2789eac277b3",
        "title": "Some Book About Something",
        "author": "Some Guy; Another Guy"
      },
      "loanDate": "2018-06-01T11:12:00Z",
      "dueDate": "2525-01-01T11:12:00Z",
      "overdue": false
    }
  ]
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to get account -- unauthorized

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

account not found

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /patron/account/{id}/item/{itemId}/renew

Renews a loan on the item for the user

POST /patron/account/{id}/item/{itemId}/renew
URI Parameters
  • id: required (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}$)

    The UUID of a FOLIO user

  • itemId: required (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}$)

    The UUID of a FOLIO item

Response 201

Returns the renewed loan data

Body

Media type: application/json

Example:

{
  "id": "9a171a89-baca-4f1a-b2c4-d7253854864e",
  "item": {
    "instanceId": "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
    "itemId": "7d9dfe70-0158-489d-a7ed-2789eac277b3",
    "title": "Some Book About Something",
    "author": "Some Guy; Another Guy"
  },
  "loanDate": "2018-06-01T11:12:00Z",
  "dueDate": "2525-01-01T11:12:00Z",
  "overdue": false
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to renew loan -- unauthorized

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /patron/account/{id}/item/{itemId}/hold

Creates a hold request on an existing item for the user

POST /patron/account/{id}/item/{itemId}/hold
URI Parameters
  • id: required (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}$)

    The UUID of a FOLIO user

  • itemId: required (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}$)

    The UUID of a FOLIO item

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 201

Returns data for a new hold request on the specified item

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /patron/account/{id}/instance/{instanceId}/hold

Creates a hold request on an existing item by instance ID for the user

POST /patron/account/{id}/instance/{instanceId}/hold
URI Parameters
  • id: required (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}$)

    The UUID of a FOLIO user

  • instanceId: required (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}$)

    The UUID of a FOLIO instance

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 201

Returns data for a new hold request on the selected item

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Instance with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /patron/account/{id}/hold/{holdId}/cancel

cancels the request

POST /patron/account/{id}/hold/{holdId}/cancel
URI Parameters
  • id: required (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}$)

    The UUID of a FOLIO user

  • holdId: required (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}$)

    The UUID of a FOLIO instance

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 200

Returns an updated hold request after cancelling

Body

Media type: application/json

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "queuePosition": 1,
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Open - Not yet filled",
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to cancel hold -- unauthorized

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

access denied

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

hold not found

Response 422

Validation error

Body

Media type: application/json

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator