1. Patron API

A collection of endpoints for accessing Patron data.

This API refers to uin, which in many cases is equivalent to externalSystemId in FOLIO.

1.1. Get Patron Block Status

A GET to the /patron/{uin}/block endpoint which will return a boolean representing whether or not the given Patron is blocked.

Path Parameters

Table 1. /patron/{uin}/block
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Sample Request

GET /patron/1234567890/block?catalogName=folio HTTP/1.1
Content-Type: text/plain;charset=UTF-8
Accept: text/plain, text/html, application/json
Host: localhost:8080

Sample Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain
Content-Length: 4

true

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/block?catalogName=folio' -i -X GET \
    -H 'Content-Type: text/plain;charset=UTF-8' \
    -H 'Accept: text/plain, text/html, application/json'

1.2. Get Patron Fines

A GET to the /patron/{uin}/fines endpoint which will return a list of Fees or Fines associated with the given Patron. A Fee or a Fine may also be called a Charge.

Path Parameters

Table 2. /patron/{uin}/fines
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Response Fields

Path Type Description

[].fineId

String

A UUID representing a Fee or Fine.

[].itemId

String

A UUID representing the Item associated with this Fee or Fine.

[].instanceId

String

A UUID representing a Holding Record Instance associated with this Fee or Fine.

[].amount

Number

A dollar amount to be charged.

[].fineType

String

A type of the Fee or Fine.

[].fineDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Fee or Fine was accrued.

[].itemTitle

String

A title of the Item associated with this Fee or Fine.

Sample Request

GET /patron/1234567890/fines?catalogName=folio HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/html
Host: localhost:8080

Sample Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1051

[{"fineId":"d4d849f9-f953-4f7c-acf6-b16b65cb3bb4","itemId":"0b82a7d0-a681-39d9-8b11-5b09726722d9","instanceId":"bd173687-8355-3018-b2bc-eb3bfd14c869","amount":1.0,"fineType":"charge","fineDate":1556719726000,"itemTitle":"Guardians of the galaxy / Marvel Studios ; co-producers, David J. Grant, Jonathan Schwartz ; executive producers, Nik Korda, Stan Lee, Victoria Alonso, Jeremy Latcham, Alan Fine, Louis D'Esposito ; produced by Kevin Feige ; written by James Gunn and Nicole Perlman ; directed by James Gunn."},{"fineId":"e2791487-9962-4e67-98dd-99f8bc89e3e4","itemId":"13c4044e-9ecc-3c90-93df-4a58d6e0f597","instanceId":"d42f4d83-a5ab-38f4-b396-1a43a471b86f","amount":1.0,"fineType":"charge","fineDate":1566308501000,"itemTitle":"Bill & Ted's excellent adventure / an Orion Pictures release ; Nelson Entertainment presents an Interscope Communications production ; in association with Soisson/Murphey Productions ;  written by Chris Matheson & Ed Solomon ; produced by Scott Kroopf, Michael S. Murphey, Joel Soisson ; directed by Stephen Herek."}]

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/fines?catalogName=folio' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json, text/html'

1.3. Get Patron Hold Requests

A GET to the /patron/{uin}/holds endpoint which will return a list of Hold Requests associated with the given Patron.

Path Parameters

Table 3. /patron/{uin}/holds
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Response Fields

Path Type Description

[].requestId

String

A UUID representing a Hold Request.

[].itemId

String

A UUID representing the Item associated with this Hold Request.

[].instanceId

String

A UUID representing a Holding Record Instance associated with this Hold Request.

[].requestType

String

A type of the Hold Request.

[].itemTitle

String

A title of the Item associated with this Hold Request.

[].statusText

String

A descriptive status of the Hold Request.

[].pickupServicePoint

String

A title representing the Pickup Service Point location.

[].queuePosition

Number

The position within the queue.

[].requestDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Hold Request created.

[].expirationDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Hold Request will expire.

Sample Request

GET /patron/1234567890/holds?catalogName=folio HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/html
Host: localhost:8080

Sample Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 368

[{"requestId":"8bbac557-d66f-4571-bbbf-47a107cc1589","itemId":"26670295-716a-4f84-8f65-2ef31707c017","instanceId":"255f82f3-5b1b-4239-93e4-ec6acf03ad9d","requestType":"Recall","itemTitle":"I Want to Hold Your Hand","statusText":"Open - Not yet filled","pickupServicePoint":"Miller General","queuePosition":1,"requestDate":1527927390000,"expirationDate":1538468190000}]

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/holds?catalogName=folio' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json, text/html'

1.4. Cancel Patron Hold Request

A POST to the /{uin}/holds/{requestId}/cancel endpoint to cancel a Hold Request associated with the given Patron.

Path Parameters

Table 4. /patron/{uin}/holds/{requestId}/cancel
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

requestId

A UUID representing a Hold Request.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Sample Request

POST /patron/1234567890/holds/8bbac557-d66f-4571-bbbf-47a107cc1589/cancel HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/html
Host: localhost:8080

catalogName=folio

Sample Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/holds/8bbac557-d66f-4571-bbbf-47a107cc1589/cancel' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json, text/html' \
    -d 'catalogName=folio'

1.5. Get Patron Loans

A GET to the /patron/{uin}/loans endpoint which will return a list of Loans associated with the given Patron. A Loan may also be called a Loan Item or a Charged Item.

Path Parameters

Table 5. /patron/{uin}/loans
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Response Fields

Path Type Description

[].loanId

String

A UUID representing a Loan.

[].itemId

String

A UUID representing the Item associated with this Loan.

[].instanceId

String

A UUID representing a Holding Record Instance associated with this Loan.

[].instanceHrid

String

A human-readable number representing associated with this Loan.

[].itemType

String

A itemType of the Loan.

[].loanDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Loan was created.

[].loanDueDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Loan is due.

[].overdue

Boolean

Designates that the Loan is overdue.

[].title

String

A title of the Loan.

[].author

String

A author of the Loan.

[].locationCode

String

A locationCode of the Loan.

[].location

String

A location of the Loan.

[].canRenew

Boolean

A canRenew of the Loan.

Sample Request

GET /patron/1234567890/loans?catalogName=folio HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/html
Host: localhost:8080

Sample Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1793

[{"loanId":"5667d646-6b40-46f9-80bb-d965a46e7116","itemId":"04dbd368-5952-3779-9bcd-563cd2c53746","instanceId":"69dd6864-4d52-387c-b5b2-8db1ce8f5013","instanceHrid":"in00003570562","itemType":"normal","loanDate":1525989640000,"loanDueDate":1633744800000,"overdue":false,"title":"Rising strong / Brené Brown.","author":"Brown, Brené,","location":"Evans Library Stacks","locationCode":"stk","canRenew":true},{"loanId":"0003fb96-3b67-42f9-be46-643462ac3ee4","itemId":"400f84bc-5400-3987-b87e-14940bd57334","instanceId":"f29d73fc-b4ef-3616-be63-cacf0b853c3e","instanceHrid":"in00002535779","itemType":"normal","loanDate":1455056347000,"loanDueDate":1633744800000,"overdue":false,"title":"Military economics : the interaction of power and money / Ron Smith.","author":"Smith, Ron, 1946 September 2-","location":"Evans Library Stacks","locationCode":"stk","canRenew":true},{"loanId":"b7c200ba-6e34-4222-9b53-cc22625fa627","itemId":"a4c4ec98-f7ae-365c-8597-dc151c173c65","instanceId":"a0480d3f-181e-3abd-a091-288e1cfc05ab","instanceHrid":"in00000295952","itemType":"normal","loanDate":1295984118000,"loanDueDate":1633744800000,"overdue":false,"title":"Philosophy of logic / [by] W. V. Quine.","author":"Quine, W. V. (Willard Van Orman)","location":"Evans Library Stacks","locationCode":"stk","canRenew":true},{"loanId":"adbe373f-89ec-44e9-8840-f6906adc7adf","itemId":"f5a63a6f-4b1d-3a75-8fba-668efffae4ad","instanceId":"829fecd3-67c3-3ca2-b9d4-281227690e0f","instanceHrid":"in00003466399","itemType":"normal","loanDate":1496336617000,"loanDueDate":1633734000000,"overdue":false,"title":"Spam nation : the inside story of organized cybercrime--from global epidemic to your front door / Brian Krebs.","author":"Krebs, Brian,","location":"Evans Library Stacks","locationCode":"stk","canRenew":true}]

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/loans?catalogName=folio' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json, text/html'

1.6. Renew Patron Loan

A POST to the /{uin}/renew/{itemId} endpoint to renew an Loan associated with the given Patron. A Loan may also be called a Loan Item or a Charged Item. This endpoint renews by the itemId, instead of the loanId. The renewed Loan is returned in the response.

Path Parameters

Table 6. /patron/{uin}/renew/{itemId}
Parameter Description

uin

The Patron UIN.

In FOLIO, this is the externalSystemId.

itemId

A UUID representing the Item associated with this Loan.

Request Parameters

Parameter Description

catalogName

A name of the catalog to use.

The catalog settings are loaded from src/main/resources/catalogs/{catalogName}.json file.

This endpoint defaults to folio.

Response Fields

Path Type Description

loanId

String

A UUID representing a Loan.

itemId

String

A UUID representing the Item associated with this Loan.

instanceId

String

A UUID representing a Holding Record Instance associated with this Loan.

instanceHrid

String

A human-readable number representing associated with this Loan.

itemType

String

A itemType of the Loan.

loanDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Loan was created.

loanDueDate

Number

A timestamp in milliseconds from UNIX Epoch representing the date the Loan is due.

overdue

Boolean

Designates that the Loan is overdue.

title

String

A title of the Loan.

author

String

A author of the Loan.

locationCode

String

A locationCode of the Loan.

location

String

A location of the Loan.

canRenew

Boolean

A canRenew of the Loan.

Sample Request

POST /patron/1234567890/renew/f5a63a6f-4b1d-3a75-8fba-668efffae4ad?catalogName=folio HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/html
Content-Length: 529
Host: localhost:8080

{
  "loanId": "adbe373f-89ec-44e9-8840-f6906adc7adf",
  "loanDate": 1496336617000,
  "loanDueDate": 1633734000000,
  "itemId": "f5a63a6f-4b1d-3a75-8fba-668efffae4ad",
  "itemType": "normal",
  "instanceId": "829fecd3-67c3-3ca2-b9d4-281227690e0f",
  "instanceHrid": "in00003466399",
  "overdue": false,
  "title": "Spam nation : the inside story of organized cybercrime--from global epidemic to your front door / Brian Krebs.",
  "author": "Krebs, Brian,",
  "locationCode": "stk",
  "location": "Evans stk",
  "canRenew": true
}

Sample Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 475

{"loanId":"adbe373f-89ec-44e9-8840-f6906adc7adf","itemId":"f5a63a6f-4b1d-3a75-8fba-668efffae4ad","instanceId":"829fecd3-67c3-3ca2-b9d4-281227690e0f","instanceHrid":"in00003466399","itemType":"normal","loanDate":1496336617000,"loanDueDate":1633734000000,"overdue":false,"title":"Spam nation : the inside story of organized cybercrime--from global epidemic to your front door / Brian Krebs.","author":"Krebs, Brian,","location":"Evans stk","locationCode":"stk","canRenew":true}

Example Curl Request

$ curl 'http://localhost:8080/patron/1234567890/renew/f5a63a6f-4b1d-3a75-8fba-668efffae4ad?catalogName=folio' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json, text/html' \
    -d '{
  "loanId": "adbe373f-89ec-44e9-8840-f6906adc7adf",
  "loanDate": 1496336617000,
  "loanDueDate": 1633734000000,
  "itemId": "f5a63a6f-4b1d-3a75-8fba-668efffae4ad",
  "itemType": "normal",
  "instanceId": "829fecd3-67c3-3ca2-b9d4-281227690e0f",
  "instanceHrid": "in00003466399",
  "overdue": false,
  "title": "Spam nation : the inside story of organized cybercrime--from global epidemic to your front door / Brian Krebs.",
  "author": "Krebs, Brian,",
  "locationCode": "stk",
  "location": "Evans stk",
  "canRenew": true
}
'