Patron management

Authenticate patron

Subscribe patron

There are two endpoints for subscribing a patron. The first one is used for new patrons and the second one for subscribing patrons in a new library or re-subscribing patrons in libraries where they previously had a membership.

The outcome of the login endpoint determines which one should be used.

If the ‘authenticate’ patron does not return a patronSystemId then the first one (/library/{libraryId}/patron) should be used, otherwise the second one should be used (/library/{libraryId}/patron/{patronSystemId}).

Re-subscription of patrons can only be done if the patron has no active subscription in the given library, or when the subscription is ending at the end of the current month.

Method 1: new patrons

Type: POST

Request: /library/{libraryId}/patron

Parameters

• LibraryId: this is the id (instantie_id) from the library the patron wants to subscribe

Data:

{

"initials": "",

"firstName": "",

"lastName": "",

"dateOfBirth": "",

"addresses": [

{

"street": "",

"houseNumber": "",

"addition": "",

"zipCode": "",

"city": "",

"region": "",

"country": "",

"type": "H",

"typeLabel": "",

"method": ""

}

],

"phoneNumber": "",

"emailAddress": "",

"homeBranch": “”,

"identificationNumber": {

"identificationType": "EID",

"identificationNumber": ""

},

"preferredLanguage": "",

"patronSystemId":””,

"password": "",

"username": "”

"gender": "",

"smsNumber": "",

"futureSubscriptionId": “”,

"acceptedTermsAndAgreement": "true"

}

The bold lines are mandatory, and if they are not supplied this will lead to an error.

The field “homeBranch” is the branch in which the patron wants a new subscription. If this branch is not one of the libraries from the library-id in the parameter a 500-error will be thrown.

Response:

• PatronId: contains the new generated actor_id.
• PatronSystemId: contains the new generated unique id for this patron.
• SubscriptionStatus: the current subscription status for this new patron.
• PaymentId: a unique identifier that can be used to pay the subscription via Ideal/Rest if the status is not ‘INVOICE’.

Sample:

{"id":"","validationErrors":[],"patronId":1516143,"patronSystemId":"9d6d1e8ae0a47b43988971ffa4834126","initials":"T.","firstName":"Test","lastName":"Testuser","prefix":"","suffix":"","dateOfBirth":"1980-01-01","addresses":[{"id":"","links":[{"rel":"self","href":"/restapi/country/nl/address"}],"validationErrors":[],"street":"Machlaan","houseNumber":"5","addition":"","zipCode":"9765 TK","city":"Eelde","region":"","country":"Nederland","type":"H","typeLabel":"Hoofdadres"}],"phoneNumber":"0612345678","emailAddress":"test@testdomain.org","membershipExpirationDate":"2022-05-31","homeBranch":"9042","language":"nl_NL","updatedPassword":false,"username":"test.tester123","gender":"MALE","libraryCards":[{"id":"","validationErrors":[],"cardNumber":"2X748933357884","type":"H","mainCard":true}],"showResetPinEditLink":false,"selfPayAllowed":false,"smsNumber":"0612345678","subscriptionId":45,"subscriptionStatus":"INVOICE","preferredName":"","paymentId":"cd4f288bbb23897050884b6171d2f326","displayName":"Tester, T,","title":"","membershipDescription":"Default subscription","middleName":"","customerTag":"","registrationDate":"2021-05-12T00:00:00","homeBranchName":"Raalte","showLoanHistory":"B"}

Method 2: re-subscribe patrons

Type: PUT

Request: /library/{libraryId}/patron/{patronSystemId}

Parameters

• LibraryId: this is the id (instantie_id) from the library the patron wants to subscribe
• PatronSystemId: this is the id that was obtained by the ‘authorization’ request (patron/authentication/library/{libraryId})

Data:

{

"initials": "",

"firstName": "",

"lastName": "",

"dateOfBirth": "",

"addresses": [

{

"street": "",

"houseNumber": "",

"addition": "",

"zipCode": "",

"city": "",

"region": "",

"country": "",

"type": "H",

"typeLabel": "",

"method": ""

}

],

"phoneNumber": "",

"emailAddress": "",

"homeBranch": “”,

"identificationNumber": {

"identificationType": "EID",

"identificationNumber": ""

},

"preferredLanguage": "",

"patronSystemId":””,

"password": "",

"username": "”

"gender": "",

"smsNumber": "",

"subscriptionId": “”,

"acceptedTermsAndAgreement": "true"

}

The bold lines are mandatory and will lead to an error if not supplied.

 Note:  patronSystemId is also mandatory.

One of the requirements to subscribe a patron is that in the subscriptions table in Wise for every library, a definition for customer-type ‘N’ (anonymous) is available. Without this definition, a subscription cannot be completed.

Pay subscription fees

If the option VWIZBET is not set in Wise, a subscription will not be activated and will remain in the shopping basket until the payment is completed. The payment ID from the subscription endpoint should be used to complete the subscription.

Type: POST

Request: /payment/{paymentId}/status/{paymentStatus}

Parameters:

• PaymentId: the ID that came in the response from the subscription endpoint
• PaymentStatus: SUCCESS. For other statuses, see the Swagger documentation.

Response:

A default message code 200 is given if the payment is handled successfully.

Before a client can call this endpoint, the client first needs to authorize itself with a special account (username and password) provided by the library organization. It is required that the IP address of the client is added to the safe list.

The token in the response is needed to complete the payment and should be used in the header of the payment endpoint.

Retrieve blocks for a specific patron

With this endpoint, the current blocks for a patron can be retrieved.

Type: GET

Request:     /patronmanagement/patron/{patronSystemId}/library/{libraryId}/property/blocking

Parameters

• PatronSystemId: this is the id that was obtained by the ‘authorization’ request (patron/authentication/library/{libraryId})
• LibraryId: this is the id (instantie_id) from the library where the block is active.

Response:

{

 "id":"",

 "validationErrors":[],

 "addressBlock":false,

 "generalBlock":false,

 "onlineBlock":false,

 "customerAtTerminalBlock":false,

 "webPortalSelfServiceBlock":false,

 "collectionAgencyBlock":false,

 "patronCardBlock":false,

 "blockMessage":"",

 "blockDetails":""

}

Set or remove one or more blocks for a patron

With this endpoint it is made possible to set or remove a few blocks on a specific patron.

Type: PUT

Request:     /patronmanagement/patron/{patronSystemId}/library/{libraryId}/property/blocking

• PatronSystemId: this is the ID that was obtained by the ‘authorization’ request (patron/authentication/library/{libraryId})
• LibraryId: this is the id (instantie_id) from the library where the block should be activated or deactivated

Data:

{

 "id":"",

 "validationErrors":[],

 "addressBlock":false,

 "generalBlock":false,

 "onlineBlock":false,

 "customerAtTerminalBlock":false,

 "webPortalSelfServiceBlock":false,

 "collectionAgencyBlock":false,

 "patronCardBlock":false,

 "blockMessage":"",

 "blockDetails":""

}

Set the required type of block on ‘true’ to activate the block. Set it to "false" to deactivate it.

In the response, the current situation is returned.

Response:

{

 "id":"",

 "validationErrors":[],

 "addressBlock":false,

 "generalBlock":false,

 "onlineBlock":false,

 "customerAtTerminalBlock":false,

 "webPortalSelfServiceBlock":false,

 "collectionAgencyBlock":false,

 "patronCardBlock":false,

 "blockMessage":"",

 "blockDetails":""

}

Before this call can be done, the client needs to be logged in. The client needs at least Read permissions on the ‘actor’, on the library level.

Getting a list of updated patrons

For synchronizing patrons with other systems you need a list of patrons which are recently updated. Using the endpoint

Request : GET /patronmanagement/patron/library/{libraryid}/updatedpatron?date=yyyy-mm-dd

Response: 

{
"patronSystemIDs" : [
        "45jherg678934434 krhf9w876r....",
        "59wef8fewj45yulk9yul6yl6946..."
    ]
}

The response of this endpoint contains a list of uuids of the patrons. Now it is possible to get patron information from every patron to update the information stored in the other system

Getting a list of deleted patrons

For synchronizing patrons with other systems you need a list of patrons which are recently updated. Using the endpoint

Request : GET /patronmanagement/patron/library/{libraryid}/deletedpatron?date=yyyy-mm-dd

Response: 

{
"patronSystemIDs" : [
        "45jherg678934434 krhf9w876r....",
        "59wef8fewj45yulk9yul6yl6946..."
    ]
}

The response of this endpoint contains a list of uuids of the patrons. Now it is possible to delete the patron information in the other system based on this uuid.

Get a list of active subscriptions by searching email or EID

For checking whether a patron already has an active subscription when filling out an online subscription form. 

Type: POST

Request: /patronmanagement/duplicate

Parameters:

• searchValue: "email address" or "EID number"
• searchType: "EMAIL" or "EID"

Response:

    {

        "patronSystemId": "6fc35db94ef7565ebbea34643575f729",

        "subscriptionData": [

            {

                "libraryId": "I304",

                "subscriptionEndDate": "2024-10-30",

                "status": "5"

      }

The response of this endpoint contains a list of active subscriptions for this patron based on their email address or EID.