Skip to content

Integration Guides

Jump to bottom Edit New page
Kodo Korkalo edited this page Aug 25, 2026 · 12 revisions

This part of wiki contains information related to connecting external services to Koha via APIs. The target audience (external software and hardware providers) differs from the rest of the wiki, so these documents are in english unlike the rest of the wiki.

Borrower identification APIs

We currently support two main ways for identifying and authenticating library borrowers. Identification can either be done with either:

  1. Borrowers/status API-endpoint
  2. 3M SIP2 over SIPoHTTP using either 63/64 or 23/24 message pair

Of the two borrowers/status is preferred, because of its simplicity and ease of account management.

Borrowers/status API endpoint

You can send GET or POST requests to borrowers/status endpoint, both methods work identically and will receive identical json-response from the API. With both methods (yes, GET too) the parameters of the request must be transmitted in the request body, not the URL. This is to ensure that no confidential information will end up in web-server logs.

The URL of these endpoints are in the form of https://[k].koha-suomi.fi/api/v1/contrib/kohasuomi/borrowers/status, where [k] is the name of the target Koha instance.

Here's an example request using cURL:

curl -X GET \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  -d 'uname=123456789&passwd=userpasswordorpincode' \
  'https://[k].koha-suomi.fi/api/v1/contrib/kohasuomi/borrowers/status'

The endpoint will respond with json-block containing basic information about the patron that is logging in like this:

{
  "age":25,
  "borrowernumber":10000,
  "card_reported_lost":false,
  "cardnumber":"123456789",
  "charge_privileges_denied":false,
  "email":"email@domain.com",
  "excessive_outstanding_fines":false,
  "fines":0,
  "firstname":"Firstname Middlename",
  "hold_privileges_denied":false,
  "homebranch":"BRANCHCODE",
  "language":"fi-fi",
  "recall_overdue":false,
  "recall_privileges_denied":false,
  "renewal_privileges_denied":false,
  "surname":"Surname",
}

This endpoint will not provide you with address or contact information of the patron logging in.

Sipmessages API endpoint

Alternatively you can use either SIP2-message 63 (Patron information request) or 23 (Patron status request) for borrower identification. See the next section (SIPoHTTP Integration Guide) for details and an example on how to identify users with 63/64 SIP2 messages.

SIPoHTTP Integration Guide

SIPoHTTP endpoint enables interaction with a SIP2 (Standard Interchange Protocol Version 2) server via HTTP POST requests. This section explains how to use the SIPoHTTP API to authenticate and send SIP2 messages to a Koha SIP2 server for tasks such as borrower identification, status checks, and other library client operations.

For details about the SIP2 protocol, refer to the 3M™ Standard Interchange Protocol Version 2.00.

Prerequisites

  • A valid SIP2 account (login and password) on the Koha SIP2 server
  • Access to the Koha instance's SIPoHTTP API endpoint
  • Basic understanding of SIP2 message formats (see the 3M SIP2 documentation for specifics)

API Endpoint

The SIPoHTTP API endpoint is available at:

https://[k].koha-suomi.fi/api/v1/contrib/kohasuomi/sipmessages

Replace [k] with the name of target Koha instance.

Authentication

Authentication uses SIP2 account credentials, passed as attributes in the XML request body:

  • login: Your SIP2 username
  • password: Your SIP2 password

Request Format

Requests must be sent as a POST with the following headers:

Content-Type: application/xml  
Accept: application/xml

The request body must contain an XML-wrapped SIP2 message. The structure is as follows:

<ns1:sip  
    login="SIP2LOGIN"  
    password="SIP2PASSWORD"  
    xsi:schemaLocation="https://koha-suomi.fi/sipschema.xsd"  
    xmlns:ns1="https://koha-suomi.fi/sipschema.xsd"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
    <request>SIP2_MESSAGE</request> 
</ns1:sip>

Replace the following placeholders:

  • SIP2LOGIN: Your SIP2 username
  • SIP2PASSWORD: Your SIP2 password
  • SIP2_MESSAGE: The raw SIP2 message

Example: Borrower Identification

Borrower identification can use either of these SIP2 messages:

  • Message 63 (Patron Information Request)
  • Message 23 (Patron Status Request)

The following example uses the 63/64 message pair for borrower identification. 23/24 will work in similar fashion but provide more limited information about the patron in response.

Request

curl -X POST \
  --header 'Content-Type: application/xml' \  
  --header 'Accept: application/xml' \
  -d '
<ns1:sip  
    login="SIP2LOGIN"  
    password="SIP2PASSWORD"  
    xsi:schemaLocation="https://koha-suomi.fi/sipschema.xsd"  
    xmlns:ns1="https://koha-suomi.fi/sipschema.xsd"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
    <request>6300020250708    135821          AOBRANCHCODE|AA123456789|ADuserpasswordorpincode</request>  
</ns1:sip>' \
  'https://[k].koha-suomi.fi/api/v1/contrib/kohasuomi/sipmessages'

SIP2 Message Breakdown (Message 63)

The SIP2 message in the <request> field follows the SIP2 protocol format. For Message 63 (Patron Information Request), the structure is:

  • 63: Message type (Patron Information Request)
  • 000: Transaction ID (adjust as needed)
  • 20250708: Request date
  • 135821: Request time
  • AOBRANCHCODE: Branch code (replace BRANCHCODE with your library branch code)
  • AA123456789: Patron identifier (e.g., library card number)
  • ADuserpasswordorpincode: Patron password or PIN

For details on constructing SIP2 messages, refer to the 3M™ Standard Interchange Protocol Version 2.00.

Response

The server responds with an XML-wrapped SIP2 message (e.g., Message 64 for Patron Information Response). Example:

<ns1:sip  
    xmlns:ns1="https://koha-suomi.fi/sipschema.xsd"  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
    xsi:schemaLocation="https://koha-suomi.fi/sipschema.xsd">  
    <response>64              00020250708    135822000000000005000500000002AOBRANCHCODE|AA123456789|AEPatron Name|BLY|CQY|BV12.0|CC14.99|BDPatron address|BEemail@domain.com|PB20000101|PCBORROWERCATEGORY|PIY|AFGreetings from Koha.  -- Patron owes 12.00|PA1|</response>  
</ns1:sip>

SIP2 Response Breakdown (Message 64)

The <response> field contains the SIP2 response message. For Message 64 (Patron Information Response), the fields may include:

  • 64: Message type (Patron Information Response)
  • 000: Transaction ID (matches the request)
  • 20250708: Response date
  • 135822: Response time
  • AOBRANCHCODE: Branch code
  • AA123456789: Patron identifier
  • AEPatron Name: Patron's full name
  • BLY: Patron status (e.g., valid, expired, barred)
  • CQY: Charge privileges (e.g., yes/no)
  • BV12.0: Total fines owed
  • CC14.99: Currency type and amount
  • BDPatron address: Patron's address
  • BEemail@domain.com: Patron's email
  • PB20000101: Date of birth
  • PCBORROWERCATEGORY: Patron category
  • PIY: Patron ID verification
  • AFGreetings from Koha.: Custom message (e.g., fines notification)
  • PA1: End of message

For a full list of SIP2 fields and their meanings, consult the 3M™ Standard Interchange Protocol Version 2.00.

Common SIP2 Messages for Library Operations

Message Type Code Description Use Case
Patron Information Request 63 Requests detailed patron information Borrower identification, account details
Patron Information Response 64 Response to Message 63 Returns patron data
Patron Status Request 23 Requests basic patron status Quick status check (e.g., valid/invalid)
Patron Status Response 24 Response to Message 23 Returns basic status
Item Information Request 17 Requests detailed item information Retrieve item details (e.g., title, status)
Item Information Response 18 Response to Message 17 Returns item data
Checkout 11 Checks out an item to a patron Loan operations
Checkin 09 Returns an item Return operations
Renew 29 Renews an item Loan renewal

For more message types and their formats, refer to the 3M™ Standard Interchange Protocol Version 2.00.

Error Handling

  • If authentication fails (invalid SIP2 login or password), the API returns an HTTP 401 Unauthorized error
  • If the SIP2 message is malformed, the server may return an HTTP 400 Bad Request error or a SIP2 error response (e.g., 96 for Patron Status Response with an error flag)
  • Always validate the SIP2 response fields for errors (e.g., AF field for error messages)

References

Koha-Suomi REST API documentation

Full Koha-Suomi RESTful API documentation is available with respective target Koha installations.

Base URL: https://[k].koha-suomi-fi/api/v1/.html (Replace [k] with the target Koha instance subdomain.)

Architecture

  • RESTful: Stateless, resource-oriented design.
  • CRUD: Full GET, POST, PUT, DELETE support.
  • JSON: Standard payload serialization (excluding sipmessages, which uses XML envelopes for SIP2 data).
  • HTTPS: TLS-secured endpoints.

Integration Features

  • Idempotency: Safe retries for PUT/DELETE.
  • Pagination: ?limit=50&offset=100 (available on some endpoints).
  • Auth: OAuth2/API key (instance-specific).

Best Practices

  • Secure Credentials: Never hardcode credentials in client code. Use environment variables or secure configuration management
  • HTTPS: Always use HTTPS, this is mandatory
  • Rate Limiting: Respect the Koha server's rate limits, do not needlessly send duplicate or multiple requests
  • Privacy considerations: Do not store borrower information client-side for extended periods of time, always work with minimal viable borrower data
  • Stateless connections: Do not unnecessarily "ping" for connection while the client is not in need of server connection
  • Logging: Log requests and responses for debugging, but redact sensitive data (e.g., patron information and passwords)
Add a custom footer
Add a custom sidebar

Clone this wiki locally