Patron settings

What you can build

Patrons choose their usual library once, and new reservations go there unless they choose otherwise (2.5.8).

Typical flow

1. The client reads the locations the patron may choose from GetPatronConfiguration, or else from GetLocations.
2. The patron chooses a branch and, where there are any, a section inside it.
3. The client saves the choice as pickupLocation with UpdatePatronInformation.

What the API provides

• When reservation.pickupLocations is set in GetPatronConfiguration, also as an empty list, it replaces the locations from GetLocations.
• A pick-up location can be a section inside a branch.
• pickupLocation in patron.fields from GetConfiguration has the form branch_id_and_sections (the default) or only_branch_id.

What you can build

Patrons keep their own email address up to date, so the library can reach them and, where the library system supports it, send reminders by email.

Typical flow

1. The client shows the patron's addresses from GetPatronInformation.
2. The patron adds, changes or removes an address.
3. The client sends the list as emails with UpdatePatronInformation.

What the API provides

• At most one address can be default.
• maxNumberOfEmailAddresses in patron.fields from GetConfiguration is the most addresses a patron can have. More gives error 100211.
• With verification set to verify_by_email, the provider sends an email to confirm the address. verified shows the state: yes, no or pending.
• A field left out of UpdatePatronInformation is not changed. A 202 response means the update was received and is processed later.

What you can build

Patrons keep their own phone number up to date, so the library can reach them and, where the library system supports it, send reminders by text message.

Typical flow

1. The client shows the patron's numbers from GetPatronInformation.
2. The patron adds, changes or removes a number.
3. The client sends the list as phoneNumbers with UpdatePatronInformation.

What the API provides

• A number is in E.164 format and has type mobile or landline. At most one can be default.
• patron.fields from GetConfiguration gives the most numbers per type, and whether a mobile number is confirmed by text message (verify_by_sms). Too many numbers gives error 100215.

What you can build

A settings page with a switch for each kind of notification, so patrons only get the reminders they want, by the channel they prefer.

Typical flow

1. The client fetches the settings with GetPatronNotificationSettings.
2. Each notification type is shown with the delivery methods it offers and the ones the patron has chosen.
3. The patron changes a choice, and the client sends it with UpdatePatronNotificationSettings.

What the API provides

• Delivery methods are sms, email, postal and vendor. With vendor, the event goes to your own backend (2.9.1).
• delivery.methods is what the type offers; delivery.chosen is what the patron has picked.
• category suggests how the types can be grouped on the screen.
• Only the types in the request are changed. The update is all or nothing, and the response holds every setting.

Typical flow

1. The client fetches the consents with GetPatronConsents.
2. The patron gives or withdraws a consent.
3. The client sends the choice with UpdatePatronConsent.

What the API provides

• available lists each consent with its newest version. evaluated holds what the patron has chosen, and for which version.
• The known consent type is loan_history (2.8.1). Providers may offer others.
• Only the consents in the request are changed. The update is all or nothing.

What you can build

Patrons can use their right to erasure without contacting the library. Personal information and loan history are removed from the library system, and the deletion cannot be undone.

Typical flow

1. The client can first check for active loans (2.4.1) and unpaid fees (2.7.1). The check only helps the patron; the library system decides.
2. The patron confirms that the account should be deleted.
3. With a password, the client calls DeletePatron with the patron's ID or identifier and the password.
4. With an identity provider, the client gets a URL from GetDeletePatronUrl, the patron confirms there, and the provider returns to CallbackPatronDelete with a code. The client finishes with DeletePatronByCodeAndCodeVerifier.
5. The response status tells where the deletion stands. With waiting_for_acknowledgement, the client calls the deletion again with the acknowledgement code to start it. The status ends as done or deletion_error.

What the API provides

• patron.deletion in GetConfiguration lists the identifier types and identity providers the provider accepts for deletion.
• A password is always required when deleting without an identity provider.
• The identity provider flow uses PKCE: code_challenge in the first call, code_verifier in the last.
• Error 100101 means the patron still has something unresolved with the library, such as a loan or a fee.
• The provider can send the event patron_deleted to your backend (2.9.1).

What you can build

Patrons change their own password or PIN code, whichever the library system uses, from inside your service.

Typical flow

1. The client reads which credentials the patron can change from patron.credentials.changeable in GetConfiguration.
2. The patron enters the current value and the new one.
3. The client calls ChangePatronCredential with credential set to password or pin.
4. A 204 response means the change is done and the old value no longer works.

What the API provides

• The values are named after the credential: currentPassword and newPassword, or currentPin and newPin. A password and a PIN code cannot be mixed up.
• A wrong current value gives error 100001. A new value the provider will not accept gives 100011, and the info should say why. A credential that cannot be changed gives 100013.
• PLAS sets no format for a password or a PIN code.
• The provider is expected to limit attempts per patron, and should answer 429 rather than 400 when the limit is reached.
• A patron who does not know their current value resets it instead (2.2.5).

What you can build

A profile page with the patron's basic information as the library has it, including whether anything is blocked and why.

Typical flow

1. The client fetches the patron with GetPatronInformation.
2. The profile shows name, address, email addresses, phone numbers, pick-up location and permissions.

What the API provides

• fullName is always there. givenName and surname only come when the library system stores the name in parts.
• permissions lists what the patron is allowed or blocked from, with a reason when blocked. Suggested types are off_hours, self_service and exclusion.