Patron API Requests, Responses, and Error Messages

The Patron API (URL) product enables your library to transmit patron data in HTML format to third-party vendors. To access the data, the third-party application sends a request to Patron API, which returns a response or error to the requesting application. The syntax for these requests and the possible responses and errors the system might encounter are described below. For more information about this product, see Sharing Patron Record Data with Third-party Systems.

Patron API Request Syntax

Patron API can receive two types of requests: a request for patron record data, and a request to validate the patron's PIN.

Requests for patron record data must be sent to Patron API in the following format:

<protocol>://<library URL>:<port>/PATRONAPI/<identifier>/dump

PIN verification requests must be in the following format:

<protocol>://<library URL>:<port>/PATRONAPI/<identifier>/<PIN>/pintest

Request elements are as follows:

Protocol: For standard Patron API, enter http.; For Patron API with SSL, enter https.
Library URL: Enter the IP address or fully qualified domain name of your library's Innovative server (for example, 123.456.789.012 or catalog.library.org).
Port: For standard Patron API, enter 4500.; For Patron API with SSL, enter 54620.
Identifier: Enter the patron's record number, excluding check digit (for example: .p1100220), or the value from the patron record field your library uses to authenticate patrons (for example, the patron's barcode or unique ID).
PIN: Enter the patron's PIN. If the PIN contains any special characters, enter the characters in their corresponding ASCII code format, preceded by a percent (%) character. For example, the PIN "abc/def" would be sent as abc%2Fdef.

Examples of correctly formatted Patron API requests are:

http://catalog.library.edu:4500/PATRONAPI/.p1042120/dump

Accesses standard Patron API to request patron record .p10421208.

https://catalog.library.edu:54620/PATRONAPI/21913000482538/SwordFish/pintest

Accesses Patron API via SSL to check the PIN (SwordFish) of the patron with barcode 21913000482538.

Patron API Responses and Errors

When Patron API receives a request, it sends one of the following types of responses:

If the third-party application requested patron data, and Patron API can retrieve the patron's record, it sends back the patron record data.
If the third-party application requested patron PIN verification, and the patron's PIN information is correct, Patron API sends back a successful PIN response.
If the information received is incorrect or Patron API cannot retrieve the requested record, it sends back an error.

Patron Record Data Response

If Patron API receives a successful patron data request, it responds by sending the data from the patron's record in HTML format. Each line in the output represents the value of one fixed- or variable-length field from the patron record in the following format:

<field label>[p<field ID>]=<data>

Field Label: The short version of the field's label.
Field ID: The field number for fixed-length fields, or the field group tag for variable-length fields.
Data: The value from the field in the patron record.

Any variable-length fields your library has chosen to suppress are excluded from the output.

An example of a patron data request is below:

<HTML>
<BODY>
EXP DATE[p43]=12-31-97<BR>
PCODE1[p44]=-<BR>
PCODE2[p45]=-<BR>
PCODE3[p46]=0<BR>
P TYPE[p47]=1<BR>
TOT CHKOUT[p48]=56<BR>
TOT RENWAL[p49]=17<BR>
CUR CHKOUT[p50]=3<BR>
HOME LIBR[p53]=0000<BR>
PMESSAGE[p54]=<BR>
MBLOCK[p56]=-<BR>
REC TYPE[p80]=p<BR>
RECORD #[p81]=110220<BR>
REC LENG[p82]=1126<BR>
CREATED[p83]=01-09-97<BR>
UPDATED[p84]=06-05-97<BR>
REVISIONS[p85]=139<BR>
AGENCY[p86]=1<BR>
CL RTRND[p95]=0<BR>
MONEY OWED[p96]=$1.35<BR>
BLK UNTIL[p101]=  -  -  <BR>
CUR ITEMA[p102]=0<BR>
CUR ITEMB[p103]=0<BR>
PIUSE[p104]=0<BR>
OD PENALTY[p105]=0<BR>
ILL CHKOUT[p122]=3<BR>
PATRN NAME[pn]=Jackson, Richard<BR>
ADDRESS[pa]=322 San Diego St<BR>
ADDRESS2[ph]=El Cerrito, CA 99999<BR>
TELEPHONE[pt]=510-555-1212<BR>
UNIV ID[pu]=111111111<BR>
P BARCODE[pb]=21913000482538<BR>
</BODY>
</HTML>

Successful Patron PIN Response

If Patron API receives a successful patron PIN request, it sends the following response:

<HTML>
<BODY>
RETCOD=0<BR>
</BODY>
</HTML>

Error Messages

If Patron API cannot retrieve the requested record (for example, because the requested record does not exist or the barcode is incorrect), it sends the following response:

<HTML>
<BODY>
ERRNUM=1<BR>
ERRMSG=Requested record not found<BR>
</BODY>
</HTML>

If Patron API receives a PIN request containing an incorrect PIN, it sends the following response:

<HTML>
<BODY>
RETCOD=1<BR>
ERRNUM=4<BR>
ERRMSG=Invalid patron PIN<BR>
</BODY>
</HTML>

If Patron API receives a PIN request but the patron record does not contain a PIN, it sends the following response:

<HTML>
<BODY>
RETCOD=2<BR>
ERRNUM=4<BR>
ERRMSG=Invalid patron PIN<BR>
</BODY>
</HTML>