Register patron

Start Registration Process

PUT /api/.../patrons/id

This method allows the caller to update a patron record. This uses the workflow (conversational) model.

Request Information

Parameters
Name Type Required Description
patronData DtoPatronRegUpdateData Yes Define this parameter in the request body.
DtoPatronRegUpdateData
Property Type Nullable Description
ProcedureStep Int No Set the patron registration state machine to the last procedure step.
Answer Int Yes Value when replying to a registration procedural prompt.
PatronAccountTxnCode Int Yes ID of the transaction code that distinguishes the nature of different transactions such as Charge, Pay, Waive etc.
PatronPaymentMethod Int Yes ID of the payment method used to make the payment.
RegistrationPayment Decimal Yes The amount paid.
ReturnReceiptUrl Boolean No Return a receipt Url for a payment or waive.
Barcode String No Barcode of patron.
PatronID Int Yes ID of the patron
PatronCodeID Int No Required.
OrganizationID Int No Required. Organization ID where the patron record is registered. Used for SA settings and to record statistical data.
CreatorID Int Yes
ModifierID Int Yes
SystemBlocks Int Yes
YTDCircCount Int Yes
LifetimeCircCount Int Yes
LastActivityDate DateTime Yes
ClaimCount Int Yes
LostItemCount Int Yes
ChargesAmount Decimal Yes
CreditsAmount Decimal Yes
Registration DtoPatronRegistration No Required. Provide information about patron personal details.
DtoPatronRegistration
Property Type Nullable Description
NameFirst String Yes Required based on SA.
NameLast String No Required.
NameMiddle String Yes
NameTitle String Yes
PatronID Int No ID of the patron.
LanguageID Int Yes Language of the patron
NameSuffix String Yes
PhoneVoice1 String Yes
PhoneVoice2 String Yes
PhoneVoice3 String Yes
PhoneVoice3 String Yes
PhoneVoice3 String Yes
EmailAddress String Yes
Password String Yes
EntryDate DateTime Yes
ExpirationDate DateTime Yes
AddrCheckDate DateTime Yes
UpdateDate DateTime Yes
User1 String Yes
User2 String Yes
User3 String Yes
User4 String Yes
User5 String Yes
Gender Integer Yes
Birthdate DateTime Yes
RegistrationDate DateTime Yes
FormerID String Yes
ReadingListEnabled Boolean Yes
PhoneFAX String Yes
AltEmailAddress String Yes
SDIEmailAddress String Yes
SDIPositiveAssent Boolean Yes
ExcludeFromOverdues Boolean Yes
SDIEmailFormatID Int Yes
CollectionExempt Boolean Yes
SDIPositiveAssentDate Datetime Yes
DeliveryOptionID Int Yes
DeletionExempt Boolean Yes
ExcludeFromHolds Boolean Yes
ExcludeFromBills Boolean Yes
EmailFormatID Int Yes
PatronFirstLastName String Yes
PatronFullName String Yes
EmailFormatID Int Yes
StatisticalClassID Int Yes
Username String Yes
MergeDate DateTime Yes
MergeUserID Int Yes
MergeBarcode String Yes
EnableSMS Bool Yes
Phone1CarrierID Int Yes
Phone2CarrierID Int Yes
Phone3CarrierID Int Yes
eReceiptOptionID Int Yes
TxtPhoneNumber Byte Yes
ExcludeFromAlmostOverdueAutoRenew Boolean No Required
ExcludeFromPatronRecExpiration Boolean No Required
ExcludeFromInactivePatron Boolean No Required
StaffAcceptedUseSingleName Boolean No Required
Addresses Array of DtoPatronAddress Yes Patron can have multiple addresses
DtoPatronAddress
Property Type Nullable Description
PatronID Int No ID of the patron.
AddressID Int Yes ID of the address.
AddressTypeID Int No
AddressTypeDescription String Yes Label for the address type
AddressLabelID Int Yes Label ID for the address. Not required if AddressLabelDescription is supplied.
AddressLabelDescription String Yes Label for the address. Not required if AddressLabelID is supplied.
Verified Boolean Yes
VerificationDate Datetime Yes
PolarisUserID Int Yes
StreetOne String No
StreetTwo String Yes
StreetThree String Yes
MunicipalityName String Yes
PostalCode String No
ZipPlusFour String Yes
City String No
State String No
CountryName String No
County String Yes
Request body
application/json, text/json 
{ 
    "ProcedureStep": "1", 
    "Answer": "0", 
    "PatronID":356950, 
    "SystemBlocks":0, 
    "YTDCircCount":0, 
    "LifetimeCircCount":0, 
    "LastActivityDate": null, 
    "ClaimCount":null, 
    "LostItemCount":null, 
    "ChargesAmount":0, 
    "CreditsAmount":0, 
    "Barcode": "21756003332022", 
    "PatronCodeID": 1, 
    "OrganizationID": 3, 
    "Registration": 
    { 
        "DeliveryOptionID" : "1", 
        "EmailAddress" : "abc@gmail.com", 
        "Gender" : 1, 
        "LanguageID" :1, 
        "NameFirst" : "John", 
        "NameLast" : "Smith", 
        "Password" : "1234", 
        "RegistrationDate" : "4/11/2013", 
        "Username" : "ramarao", 
        "Addresses": 
        [ 
            { 
                "PatronID" : null, 
                "AddressID" : null, 
                "AddressTypeID" : 1, 
                "AddressTypeDescription" : "", 
                "AddressLabelID" : 1,                 
                "AddressLabelDescription" : null, 
                "Verified" : false, 
                "VerificationDate" : null, 
                "PolarisUserID": 1, 
                "StreetOne" : "Main Ave", 
                "StreetTwo" : "second street", 
                "StreetThree" : "Suite 101", 
                "MunicipalityName" : null, 
                "PostalCode" : "13210", 
                "ZipPlusFour" : "1234", 
                "City" : "syracuse", 
                "State" : "NY", 
                "CountryName" : "USA", 
                "County" : "Onondaga" 
            } 
         ] 
      } 
}

Response Information

Example
application/json, text/json 
{
    "PatronID":358059,
    "PatronCodeID":5,
    "OrganizationID":3,
    "CreatorID":1,
    "ModifierID":1,
    "Barcode":"21756003332024",
    "SystemBlocks":0,
    "YTDCircCount":0,
    "LifetimeCircCount":0,
    "LastActivityDate":null,
    "ClaimCount":null,
    "LostItemCount":0,
    "ChargesAmount":0.0,
    "CreditsAmount":0.0,
    "ProcedureStep":null,
    "Answer":0,
    "RegCharge":0.0,
    "AdditionalMessages":[],
    "DuplicateBarcodeExists":false,
    "DuplicatePatronDisplayProperties":[
        {"Name":"PatronName","Display":"Name"},
        {"Name":"Street","Display":"Street"},
        {"Name":"City","Display":"City"},
        {"Name":"PostalCode","Display":"Postal Code"},
        {"Name":"BirthDate","Display":"Birth Date"},
        {"Name":"Phone","Display":"Voice Phone 1"},
        {"Name":"Email","Display":"E-mail"},
        {"Name":"User1","Display":"ID Number"},
        {"Name":"User4","Display":"CybraryN Use Only (XXX,YYY)"},
        {"Name":"BranchName","Display":"Branch"}
    ],
    "DuplicatePatrons":
    [
        {
            "PatronID":1739,
            "PatronName":"Abrahamsen, Thomas D",
            "Barcode":"1000200541778",
            "Street":"95 Willow Avenue",
            "City":"KIAWAH ISLAND",
            "PostalCode":"29455",
            "Phone":"315-634-1234",
            "Email":"",
            "BirthDate":null,
            "BranchID":103,
            "BranchName":"Stillwater Public Library",
            "BranchAbr":"STI",
            "User1":"",
            "User2":"",
            "User3":"",
            "User4":"",
            "User5":"Mike"
        },
        {
            "PatronID":358089,
            "PatronName":"adsfadsf, asdfsdf",
            "Barcode":"asdfsdf",
            "Street":"123",
            "City":"SCHENECTADY",
            "PostalCode":"12303",
            "Phone":"",
            "Email":"",
            "BirthDate":null,
            "BranchID":3,
            "BranchName":"Amsterdam Free Library",
            "BranchAbr":"AMS",
            "User1":"",
            "User2":"",
            "User3":"",
            "User4":"",
            "User5":"Mike"
        }
    ],
    "SuggestedUserNames":[],
    "Registration":
    {
        "PatronID":358059,
        "LanguageID":1,
        "NameFirst":"Geoff",
        "NameLast":"Young",
        "NameMiddle":"D",
        "NameTitle":"Mr.",
        "NameSuffix":"",
        "PhoneVoice1":"315-634-4541",
        "PhoneVoice2":"",
        "PhoneVoice3":"",
        "EmailAddress":"jeff.young@polarislibrary.com",
        "Password":"1234",
        "EntryDate":null,
        "ExpirationDate":"2016-05-17T08:00:00Z",
        "AddrCheckDate":"2016-05-17T08:00:00Z",
        "UpdateDate":null,
        "User1":"",
        "User2":"",
        "User3":"",
        "User4":"",
        "User5":"Mike",
        "Gender":1,
        "Birthdate":"1969-12-27T10:00:00Z",
        "RegistrationDate":null,
        "FormerID":"",
        "ReadingListEnabled":false,
        "PhoneFAX":"",
        "DeliveryOptionID":1,
        "StatisticalClassID":80335,
        "CollectionExempt":true,
        "AltEmailAddress":null,
        "ExcludeFromOverdues":true,
        "SDIEmailAddress":null,
        "SDIEmailFormatID":null,
        "SDIPositiveAssent":null,
        "SDIPositiveAssentDate":null,
        "DeletionExempt":true,
        "PatronFullName":null,
        "ExcludeFromHolds":true,
        "ExcludeFromBills":true,
        "EmailFormatID":0,
        "PatronFirstLastName":null,
        "Username":"username",
        "MergeDate":null,
        "MergeUserID":null,
        "MergeBarcode":null,
        "EnableSMS":null,
        "RequestPickupBranchID":null,
        "Phone1CarrierID":1,
        "Phone2CarrierID":28,
        "Phone3CarrierID":28,
        "eReceiptOptionID":null,
        "TxtPhoneNumber":null,
        "Addresses":
        [
            {
                "PatronID":358059,
                "AddressID":0,
                "AddressTypeID":1,
                "AddressTypeDescription":null,
                "AddressLabelDescription":"Work",
                "Verified":false,
                "VerificationDate":null,
                "PolarisUserID":1,
                "StreetOne":"5077 Yellow Wood Parkway",
                "StreetTwo":"",
                "StreetThree":"",
                "MunicipalityName":null,
                "PostalCode":"13078",
                "ZipPlusFour":"1234",
                "City":"JAMESVILLE",
                "State":"NY",
                "CountryName":"USA",
                "County":"ONONDAGA"
            }
        ]
    },
    "PAPIProcedure":0,
    "PAPIProcedureStep":16,
    "PAPIAction":1,
    "PAPIActionProcedure":0,
    "PAPIPromptType":4,
    "PAPIStopType":0,
    "PAPIReturnCode":-3608,
    "Success":false,
    "Message":"Duplicate patrons are found, Do you want to continue?"
}

Processing the Results

API Procedural calls act like a “conversation”. You initiate the conversation by calling the method with a ProcedureStep value of 1 (Start).

Example:
"ProcedureStep": 1

The registration procedure will process the DtoPatron that was posted to it. It will reply to your request with a DtoPatronResult that contains a set of PAPI Values:

Example:
"PAPIProcedure":0,
"PAPIProcedureStep":16,
"PAPIAction":2,
"PAPIActionProcedure":0,
"PAPIPromptType":4,
"PAPIStopType":0,
"PAPIReturnCode":-3001,
"Success":false,
"Message":"Duplicate patrons are found, Do you want to continue?"

You should always check the PAPIReturnCode. 0 or greater represents a successful call. The procedure completed. A return code of < 0, means the call did not complete or more processing is required. In this case, a -3001 was returned. This tells us that there are duplicate patrons exist in the database. You may also look at the PAPIProcedureStep that was returned. It is set to 16, which signifies the process stopped on “DuplicatePatrons”.

Next, look at the PAPIAction value. Given the value 2 (Prompt), it is telling the caller that they need to display a prompt. The Message property contains the prompt text. The PAPIPromptType value is 4, which indicates a 'Yes/No' prompt.

The caller should display a prompt that displays the message and provide “Yes” and “No” options. Because this is a duplicate patrons return code, additional information is returned that should be displayed. The duplicate patrons array contain additional information about the existing patrons. In the native staff client, the following dialog displays:

The 'DuplicatePatronDisplayProperties' array contains a list of the properties and associated display names that should be displayed in the duplicate patrons dialog.

The caller replies to this response by calling registration again, but this time the procedure step will be set to 2. The current step is returned in the DtoPatronResult:

Example:
"PAPIProcedureStep":2

The answer is set to 1 (yes) or 0 (no).

Example:
        {
            "Barcode": "21756003332022",
            "PatronCodeID": 1,
            "OrganizationID": 3,
            "ProcedureStep": 1,
            "Answer": 1,   
            DtoPatronRegistration:  Registration
        }

Continue this process until the conversation is complete. Please note that by not replying, you are simply choosing to discontinue with the registration operation. It is a best practice to follow-through the process until the conversation is complete.

Reference for Polaris API Procedure values:

public enum PAPIProcedureStatus
{
	Error = -1,
	Exit = 0,
	Continue = 1
}

public enum PAPIProcedure
{
	None = 0,
	CheckIn = 1,
	CheckOut = 2,
	CreateOTFItem = 3,
	PatronRegistration = 4,
	PlaceHoldRequest = 5,
	RenewItemCheckout = 6
}

public enum PAPIProcedureStep
{
	None = 0,
	Start = 1,
	CheckPatronBlocks = 2,
	GetEphemeralItemCount = 3,
	CheckAssignedBranch = 4,
	PlaceItemInTransit = 5,
	PermitOvernightLoan = 6,
	NonCirculatingItemBlock = 7,
	RestrictedPatronCodeBlock = 8,
	CheckItemBlocks = 9,
	CheckOutItemInTransit = 10,
	FloatingCheckIn = 11,
	PlaceInTransit = 12,
	OutToDifferentPatron = 13,
	ResolveLostBilledItem = 14, 
	PatronRegistrationCharge = 15,
	DuplicatePatrons = 16,
	PatronAddressEmpty = 17,
    VerifyPatronDataBlock = 34,
    InvalidPostalcodeFormat = 35
}

public enum PAPIAction
{
	None = 0,
	Stop = 1,
	Prompt = 2,
	Procedure = 3
}

public enum PAPIStopType
{
	None = 0,
	Exit = 1,
	Error = 2
}

public enum PAPIPromptType
{
	None = 0,
	Warning = 1,
	Continue = 2,
	Count = 3,
	YesNo = 4,
	YesNoCancel = 5,
	Acknowledge = 6,
	ResolveLostBilledItem = 7
}

public enum PAPIPromptResult
{
	None = -1,
	No = 0,
	Yes = 1,
	OK = 2,
	Cancel = 3,
	Abort = 4,
	Retry = 5,
	Ignore = 6
}

HTTP Response Codes

Code Description
200 OK. Success
Some more native staff client dialogs during update process

The following dialog displays if required feilds are empty:

The following dialog displays if the address information is missing:

The following dialog displays if the barcode already exists: