Skip to content

User ​

Service path: /json/user

The user service covers the patron profile, settings, addresses, photos, PIN management, card lost/found reporting, and guest-deposit requests. All methods are normal RPC calls and most use the authenticated sessionId.

Get the Current User ​

Returns the full profile of the logged-in user.

plaintext
POST /json/user
method: retrieve

Parameters ​

FieldTypeRequiredDescription
sessionIdstringYESUser session (injected).
institutionIdstringYESInstitution (injected).

Request ​

json
{
    "method": "retrieve",
    "params": {
        "sessionId": "{SESSION_ID}",
        "institutionId": "{INSTITUTION_UUID}"
    }
}

Success Response ​

json
{
    "response": {
        "id": "{USER_ID}",
        "userName": "{USERNAME}",
        "firstName": "{FIRST_NAME}",
        "middleName": "{MIDDLE_NAME}",
        "lastName": "{LAST_NAME}",
        "email": "{EMAIL}",
        "phone": "{PHONE}",
        "classification": "{CLASSIFICATION}",
        "guestUser": false
    },
    "exception": null
}

NOTE

The user record is large and field coverage depends on institution configuration. The fields above are the ones GET Mobile reads directly. guestUser is a boolean that switches the app between the patron/* and guest/* route trees.

Update the Current User ​

Saves edits to the profile. The app always sends forceOverwrite: true.

plaintext
POST /json/user
method: update

Parameters ​

FieldTypeRequiredDescription
userobjectYESFull user object (typically the one from retrieve, with edits applied).
forceOverwritebooleanYESAlways true in the app.
json
{
    "method": "update",
    "params": {
        "user": { "id": "{USER_ID}", "firstName": "Ada", "lastName": "Lovelace" },
        "forceOverwrite": true,
        "sessionId": "{SESSION_ID}",
        "institutionId": "{INSTITUTION_UUID}"
    }
}

Change the Password ​

plaintext
POST /json/user
method: changePassword

Parameters ​

FieldTypeRequiredDescription
oldPasswordstringYESCurrent password.
newPasswordstringYESNew password.
sessionIdstringYESUser session (injected).

Success Response ​

json
{ "response": true, "exception": null }

IMPORTANT

Server-side password rules are stricter than the UI. The app's minimum is 7 characters, at least one number, and not one of the last 4 passwords (BadPasswordException).

Create a PIN ​

Registers a 4-character PIN for the device so the user can unlock without a password.

plaintext
POST /json/user
method: createPIN

Parameters ​

FieldTypeRequiredDescription
PINstringYES4-character PIN. Note the uppercase key.
deviceIdstringYESStable device identifier.
sessionIdstringYESUser session (injected).
json
{
    "method": "createPIN",
    "params": {
        "PIN": "1234",
        "deviceId": "{DEVICE_ID}",
        "sessionId": "{SESSION_ID}"
    }
}

NOTE

createPIN is flagged useInstitutionId = false in the app, so no institutionId is sent. If you send one anyway it is ignored.

Settings ​

Settings are key/value pairs scoped to the user. The value is always a string; booleans are "0" / "1".

Get a user setting ​

plaintext
POST /json/user
method: retrieveSetting
FieldTypeRequiredDescription
settingNamestringYESFull setting name, e.g. CashlessKey.
sessionIdstringYESUser session (injected).
json
{
    "method": "retrieveSetting",
    "params": { "settingName": "CashlessKey", "sessionId": "{SESSION_ID}" }
}

Response is a single setting object:

json
{
    "response": {
        "name": "CashlessKey",
        "value": "{CASHLESS_KEY}",
        "domain": null,
        "category": null
    },
    "exception": null
}

Save a user setting ​

plaintext
POST /json/user
method: saveSetting
json
{
    "method": "saveSetting",
    "params": {
        "settingName": "quick_amount",
        "settingValue": "25",
        "sessionId": "{SESSION_ID}"
    }
}

Delete a user setting ​

plaintext
POST /json/user
method: deleteSetting
json
{
    "method": "deleteSetting",
    "params": { "settingName": "quick_amount", "sessionId": "{SESSION_ID}" }
}

Settings the app actually uses ​

NameMeaning
CashlessKeyCBORD patron key used to build the SOA barcode. Not the student ID shown as ID: on the barcode screen.
quick_amountLast-used deposit amount.
mobileaccess_favoritesFavorited door/location ids.
defaultaddressDefault delivery address.
mobileCredentialIDPersisted mobile credential id.
get.deposit.guest.recipientsRecent guest-deposit recipients.

Photos ​

Get a photo by id ​

plaintext
POST /json/user
method: retrieveUserPhoto
FieldTypeRequired
photoIdstringYES

List a user's photos ​

plaintext
POST /json/user
method: retrieveUserPhotoList

List a user's photos with data ​

plaintext
POST /json/user
method: retrieveFullUserPhotoList

Get pending/rejected photo ​

plaintext
POST /json/user
method: retrievePendingOrRejectedUserPhoto

All four take { "userId": "{USER_ID}" } (except retrieveUserPhoto, which takes photoId).

Photo object ​

addUserPhoto sends this shape inside photo:

FieldTypeNotes
externalIdstring | nullAlways null from the app.
userIdstring | nullAlways null; the session decides ownership.
mimeTypestringAlways "image/jpg" — the app re-encodes to JPEG.
statusnumber | nullnull on upload; the server assigns it.
statusReasonstring | nullnull on upload.
datastringBase64 JPEG payload (no data-URL prefix).
idstring | nullnull on upload.
insertTime, lastUpdatedstring | nullnull on upload.
versionnumber | nullnull on upload.
typenumberSee photo type.

NOTE

After a successful upload the app marks PROFILE photos as PENDING locally and government-ID photos as ACCEPTED (review happens out of band). Deletion is a updateUserPhotoStatus call with status 4 (DELETED) and the reason "Patron deleted photo".

Photo upload settings ​

The photo screen loads the whole get.photo_upload category with retrieveSettingList and maps names by stripping underscores and lower-casing them. Expected names:

SettingConsumed as
get.photo_upload.cache_timeout_minutescacheTimeoutMinutes
get.photo_upload.display_heightdisplayHeight
get.photo_upload.display_widthdisplayWidth
get.photo_upload.max_upload_sizemaxUploadSize (MB)
get.photo_upload.save_heightsaveHeight
get.photo_upload.save_widthsaveWidth
get.photo_upload.enable_clear_photo_backgroundenableClearPhotoBackground

IMPORTANT

max_upload_size is enforced client-side only, and it is compared against the decoded size of the base64 image (data.length * 3 / 4), not the file size on disk.

How the app picks which photos to show ​

retrieveUserPhotoList returns a list of metadata objects. The app keeps only statuses PENDING, ACCEPTED, REJECTED, and WORKING, then keeps the newest entry per status (by insertTime). It then re-fetches each chosen photo by id with retrieveUserPhoto to get data. Finally it calls retrievePendingOrRejectedUserPhoto and, if that returns a PROFILE photo whose status is not ACCEPTED/WORKING, shows that instead of the approved photo.

Add a photo ​

plaintext
POST /json/user
method: addUserPhoto
FieldTypeRequiredDescription
userIdstringYESUser id.
photoobjectYESPhoto object.

Update photo status ​

plaintext
POST /json/user
method: updateUserPhotoStatus
FieldTypeRequiredDescription
photoIdstringYESPhoto id.
statusnumberYESSee photo status enum.
reasonstringNORejection reason.

Addresses ​

List addresses ​

plaintext
POST /json/user
method: retrieveUserAddressList
FieldTypeRequired
userIdstringYES
addressIdstringYES — pass "" for all

Response nests the list under response.addresses:

json
{
    "response": {
        "addresses": [
            {
                "id": "{ADDRESS_ID}",
                "nickname": "Home",
                "address1": "123 Main St",
                "address2": null,
                "city": "Boston",
                "state": "MA",
                "building": null,
                "room": null,
                "onCampus": 0,
                "latitude": 42.34,
                "longitude": -71.09
            }
        ]
    },
    "exception": null
}

Create or update an address ​

plaintext
POST /json/user
method: updateUserAddress
json
{
    "method": "updateUserAddress",
    "params": {
        "address": {
            "id": null,
            "address1": "123 Main St",
            "address2": null,
            "city": "Boston",
            "state": "MA",
            "postalcode": null,
            "country": null,
            "latitude": 42.34,
            "longitude": -71.09,
            "nickname": "Home",
            "building": null,
            "room": null,
            "onCampus": 0
        },
        "userId": "{USER_ID}",
        "sessionId": "{SESSION_ID}"
    }
}

The app fills a fixed set of fields; unset values are sent as null:

id, department, objectRevision, company, address1, address2, city, state, postalcode, country, latitude, longitude, notes, nickname, building, floor, room, crossStreet, accessCode, phone, phoneExt, onCampus.

Delete an address ​

plaintext
POST /json/user
method: deleteUserAddress
json
{
    "method": "deleteUserAddress",
    "params": {
        "addressId": "{ADDRESS_ID}",
        "userId": "{USER_ID}",
        "sessionId": "{SESSION_ID}"
    }
}

Geocode an address ​

Converts a free-form address into latitude / longitude.

plaintext
POST /json/user
method: addressToGeocode
json
{
    "method": "addressToGeocode",
    "params": {
        "address": { "address1": "123 Main St", "city": "Boston", "state": "MA" },
        "sessionId": "{SESSION_ID}"
    }
}

Response is the address object with coordinates filled in.

Lost / Found Card ​

plaintext
POST /json/user
method: reportCardLost
POST /json/user
method: reportCardFound

No parameters beyond the injected session. The app selects the method name based on a boolean. Both are enabled by settings get.feature.enable_lost_card and get.feature.enable_found_card.

Delete the Account ​

plaintext
POST /json/user
method: updateUserStatus

Sent with no parameters beyond the session. Gated by get.feature.enable_account_deletion.

Look Up a User by Cashless Fields ​

Finds a user id from arbitrary cashless lookup fields (for example card number + PIN). Used by guest deposits and self-registration.

plaintext
POST /json/user
method: retrieveUserIdByCashlessFields
FieldTypeRequiredDescription
institutionIdstringYESExplicit — this call does not use the interceptor.
sessionIdstringYESExplicit.
cashlessData.lookupFieldsarrayYESLookup field objects.
json
{
    "method": "retrieveUserIdByCashlessFields",
    "params": {
        "institutionId": "{INSTITUTION_UUID}",
        "sessionId": "{SESSION_ID}",
        "cashlessData": {
            "lookupFields": [
                { "name": "cardNumber", "value": "1234567890" }
            ]
        }
    }
}

Response is the user id string.

Guest Deposit Request ​

Sends a deposit request email to another person.

plaintext
POST /json/user
method: requestDeposit
FieldTypeRequiredDescription
recipientNamestringYESRecipient display name.
recipientEmailstringYESRecipient email address.
messagestringNONote included in the email.
depositToAccountIdstringYESAccount the funds go to.
requestAmountnumberYESAmount to request.
json
{
    "method": "requestDeposit",
    "params": {
        "recipientName": "Ada Lovelace",
        "recipientEmail": "[email protected]",
        "message": "Lunch money please",
        "depositToAccountId": "{ACCOUNT_ID}",
        "requestAmount": 25,
        "sessionId": "{SESSION_ID}"
    }
}

Registration ​

Self-service account creation. Both calls live on /json/user but are not part of the normal authenticated flow: the app uses a system session and the institution id.

Retrieve registration fields ​

Returns the institution-defined lookup fields the registration form must collect.

plaintext
POST /json/user
method: retrieveRegistrationFields
json
{
    "method": "retrieveRegistrationFields",
    "params": {
        "sessionId": "{SYSTEM_SESSION}",
        "institutionId": "{INSTITUTION_UUID}"
    }
}

Response is a field list:

json
{
    "response": {
        "lookupFields": [
            {
                "lookupFieldId": "student_id",
                "displayName": "Student ID",
                "displayOrder": 1,
                "type": 3
            }
        ]
    },
    "exception": null
}
FieldMeaning
lookupFieldIdField key to send back in registrationFields.lookupFields.
displayNameLabel shown on the form.
displayOrderSort order (ascending).
typeLookup match type: -1 undefined, 1 media value, 2 date, 3 string exact, 4 string case-insensitive, 5 string fuzzy, 6 MMID/USID.

Register ​

plaintext
POST /json/user
method: register
FieldTypeRequiredDescription
registrationInfo.institutionIdstringYESInstitution id.
registrationInfo.userNamestringYESEmail / username.
registrationInfo.passwordstringYESNew password.
registrationInfo.phonestringNOPhone number.
registrationInfo.firstName / lastNamestringGuest onlyGuest name parts.
registrationInfo.registrationFields.lookupFieldsarrayYESLookup field values.

Each lookup entry is { lookupFieldId, value }:

json
{
    "method": "register",
    "params": {
        "registrationInfo": {
            "institutionId": "{INSTITUTION_UUID}",
            "userName": "[email protected]",
            "password": "hunter2!",
            "phone": "555-555-5555",
            "registrationFields": {
                "lookupFields": [
                    { "lookupFieldId": "student_id", "value": "900123456" }
                ]
            }
        },
        "sessionId": "{SYSTEM_SESSION}"
    }
}

Guest registration ​

Guest registration uses the same method with three special lookup ids and skips the server field list:

json
{
    "registrationInfo": {
        "institutionId": "{INSTITUTION_UUID}",
        "userName": "[email protected]",
        "password": "hunter2!",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "registrationFields": {
            "lookupFields": [
                { "lookupFieldId": "guestRegistration", "value": "1" },
                { "lookupFieldId": "guestFirstname", "value": "Ada" },
                { "lookupFieldId": "guestLastname", "value": "Lovelace" }
            ]
        }
    }
}

The three fixed ids are guestRegistration, guestFirstname, and guestLastname. Guest registration is only offered when the institution enables it.

Success and errors ​

A truthy response means the account was created; the app shows the "check your email" confirmation and the user confirms via the emailed link before logging in.

Failures arrive as an exception string "{code}|{detail}". The client takes the code before |, maps it through the registration content strings, and shows the result:

CodeMessage
7001A confirmed cashless user already exists and can not be added again
9505Your password contains some weird combination, try another.
6101Cannot find a match for given user information

Other registration exceptions (UserAlreadyRegisteredException, InvalidEmailException, BadRegistrationConfirmationException, etc.) are listed in the exception reference.

Automatic Deposit Settings ​

Reads and writes the patron's automatic deposit configuration. Supported when the institution enables get.feature.enable_auto_deposits or get.feature.enable_low_balance_auto_deposit.

Get the current settings ​

plaintext
POST /json/user
method: retrieveAutoDepositSettings
FieldTypeRequiredDescription
userIdstringYESCurrent user id.
json
{
    "method": "retrieveAutoDepositSettings",
    "params": { "userId": "{USER_ID}", "sessionId": "{SESSION_ID}" }
}

Response is a single settings object, or null when the user has never configured one:

json
{
    "response": {
        "userId": "{USER_ID}",
        "active": true,
        "autoDepositType": 1,
        "amount": 25,
        "lowBalanceAmount": 10,
        "fromAccountId": "{SOURCE_ACCOUNT_ID}",
        "toAccountId": "{DEST_ACCOUNT_ID}",
        "dayOfWeek": 3,
        "dayOfMonth": 0
    },
    "exception": null
}
FieldMeaning
activeWhether auto-deposit is on.
autoDepositType0 off, 1 time-based, 2 low balance.
amountAmount added on each run.
lowBalanceAmountThreshold for low-balance deposits.
fromAccountIdFunding account (credit card or bill-me source).
toAccountIdDestination account.
dayOfWeek0–6 for weekly schedules (0 when monthly).
dayOfMonth1–31 for monthly schedules (0 when weekly).

Update the settings ​

plaintext
POST /json/user
method: updateAutoDepositSettings
FieldTypeRequired
userAutoDepositSettingInfoobjectYES

The object has the same shape as the read response. The app merges the existing settings with the form values, so fields it does not edit are preserved:

json
{
    "method": "updateAutoDepositSettings",
    "params": {
        "userAutoDepositSettingInfo": {
            "userId": "{USER_ID}",
            "active": true,
            "autoDepositType": 1,
            "amount": 25,
            "lowBalanceAmount": 10,
            "fromAccountId": "{SOURCE_ACCOUNT_ID}",
            "toAccountId": "{DEST_ACCOUNT_ID}",
            "dayOfWeek": 3,
            "dayOfMonth": 0
        },
        "sessionId": "{SESSION_ID}"
    }
}

Scheduling rules the client applies:

TypeFrequencyFields set
Time-basedWeeklydayOfWeek set, dayOfMonth: 0
Time-basedMonthlydayOfMonth set, dayOfWeek: 0
Low balance—lowBalanceAmount set; schedule fields cleared
Off—active: false; other fields left as-is

The response is the saved settings object. Turning auto-deposit off is just an update with active: false.

List eligible funding accounts ​

plaintext
POST /json/commerce
method: retrieveAutoDepositAccountList
FieldTypeRequiredDescription
userIdstringYESCurrent user id.
paymentTypenumberYES1 credit, 2 bill-me.
json
{
    "method": "retrieveAutoDepositAccountList",
    "params": {
        "userId": "{USER_ID}",
        "paymentType": 1,
        "sessionId": "{SESSION_ID}"
    }
}

The app calls this once per payment type listed in the institution setting get.deposit.auto_deposit_payment_types and merges the results into the "payment method" picker. See Commerce for the response shape.

Notification Preferences ​

Stores the device push token and notification preferences on the user record.

plaintext
POST /json/user
method: saveNotification
FieldTypeRequired
userIdstringYES
notificationobjectYES

notification:

FieldTypeDescription
idstring | nullId of the user's existing push notification record, or null on first registration. Taken from user.userNotificationInfoList (first entry with type = 8).
typenumberAlways 8 (PUSH_NOTIFICATION).
valuestringFCM / APNs device token.
providerstring"ios" or "android" (the Capacitor platform).
json
{
    "method": "saveNotification",
    "params": {
        "userId": "{USER_ID}",
        "notification": {
            "id": null,
            "type": 8,
            "value": "{FCM_OR_APNS_TOKEN}",
            "provider": "ios"
        },
        "sessionId": "{SESSION_ID}"
    }
}

type values: EMAIL = 1, PHONE = 2, PUSH_NOTIFICATION = 8.

To remove the registration on logout:

plaintext
POST /json/user
method: logoutAndRemoveUserNotification

Same parameter shape. List all registrations with:

plaintext
POST /json/user
method: retrieveAllUserNotifications
json
{
    "method": "retrieveAllUserNotifications",
    "params": { "userId": "{USER_ID}", "sessionId": "{SESSION_ID}" }
}