Appearance
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: retrieveParameters
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | YES | User session (injected). |
institutionId | string | YES | Institution (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: updateParameters
| Field | Type | Required | Description |
|---|---|---|---|
user | object | YES | Full user object (typically the one from retrieve, with edits applied). |
forceOverwrite | boolean | YES | Always 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: changePasswordParameters
| Field | Type | Required | Description |
|---|---|---|---|
oldPassword | string | YES | Current password. |
newPassword | string | YES | New password. |
sessionId | string | YES | User 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: createPINParameters
| Field | Type | Required | Description |
|---|---|---|---|
PIN | string | YES | 4-character PIN. Note the uppercase key. |
deviceId | string | YES | Stable device identifier. |
sessionId | string | YES | User 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| Field | Type | Required | Description |
|---|---|---|---|
settingName | string | YES | Full setting name, e.g. CashlessKey. |
sessionId | string | YES | User 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: saveSettingjson
{
"method": "saveSetting",
"params": {
"settingName": "quick_amount",
"settingValue": "25",
"sessionId": "{SESSION_ID}"
}
}Delete a user setting
plaintext
POST /json/user
method: deleteSettingjson
{
"method": "deleteSetting",
"params": { "settingName": "quick_amount", "sessionId": "{SESSION_ID}" }
}Settings the app actually uses
| Name | Meaning |
|---|---|
CashlessKey | CBORD patron key used to build the SOA barcode. Not the student ID shown as ID: on the barcode screen. |
quick_amount | Last-used deposit amount. |
mobileaccess_favorites | Favorited door/location ids. |
defaultaddress | Default delivery address. |
mobileCredentialID | Persisted mobile credential id. |
get.deposit.guest.recipients | Recent guest-deposit recipients. |
Photos
Get a photo by id
plaintext
POST /json/user
method: retrieveUserPhoto| Field | Type | Required |
|---|---|---|
photoId | string | YES |
List a user's photos
plaintext
POST /json/user
method: retrieveUserPhotoListList a user's photos with data
plaintext
POST /json/user
method: retrieveFullUserPhotoListGet pending/rejected photo
plaintext
POST /json/user
method: retrievePendingOrRejectedUserPhotoAll four take { "userId": "{USER_ID}" } (except retrieveUserPhoto, which takes photoId).
Photo object
addUserPhoto sends this shape inside photo:
| Field | Type | Notes |
|---|---|---|
externalId | string | null | Always null from the app. |
userId | string | null | Always null; the session decides ownership. |
mimeType | string | Always "image/jpg" — the app re-encodes to JPEG. |
status | number | null | null on upload; the server assigns it. |
statusReason | string | null | null on upload. |
data | string | Base64 JPEG payload (no data-URL prefix). |
id | string | null | null on upload. |
insertTime, lastUpdated | string | null | null on upload. |
version | number | null | null on upload. |
type | number | See 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:
| Setting | Consumed as |
|---|---|
get.photo_upload.cache_timeout_minutes | cacheTimeoutMinutes |
get.photo_upload.display_height | displayHeight |
get.photo_upload.display_width | displayWidth |
get.photo_upload.max_upload_size | maxUploadSize (MB) |
get.photo_upload.save_height | saveHeight |
get.photo_upload.save_width | saveWidth |
get.photo_upload.enable_clear_photo_background | enableClearPhotoBackground |
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| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | User id. |
photo | object | YES | Photo object. |
Update photo status
plaintext
POST /json/user
method: updateUserPhotoStatus| Field | Type | Required | Description |
|---|---|---|---|
photoId | string | YES | Photo id. |
status | number | YES | See photo status enum. |
reason | string | NO | Rejection reason. |
Addresses
List addresses
plaintext
POST /json/user
method: retrieveUserAddressList| Field | Type | Required |
|---|---|---|
userId | string | YES |
addressId | string | YES — 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: updateUserAddressjson
{
"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: deleteUserAddressjson
{
"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: addressToGeocodejson
{
"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: reportCardFoundNo 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: updateUserStatusSent 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| Field | Type | Required | Description |
|---|---|---|---|
institutionId | string | YES | Explicit — this call does not use the interceptor. |
sessionId | string | YES | Explicit. |
cashlessData.lookupFields | array | YES | Lookup 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| Field | Type | Required | Description |
|---|---|---|---|
recipientName | string | YES | Recipient display name. |
recipientEmail | string | YES | Recipient email address. |
message | string | NO | Note included in the email. |
depositToAccountId | string | YES | Account the funds go to. |
requestAmount | number | YES | Amount 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/userbut 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: retrieveRegistrationFieldsjson
{
"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
}| Field | Meaning |
|---|---|
lookupFieldId | Field key to send back in registrationFields.lookupFields. |
displayName | Label shown on the form. |
displayOrder | Sort order (ascending). |
type | Lookup 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| Field | Type | Required | Description |
|---|---|---|---|
registrationInfo.institutionId | string | YES | Institution id. |
registrationInfo.userName | string | YES | Email / username. |
registrationInfo.password | string | YES | New password. |
registrationInfo.phone | string | NO | Phone number. |
registrationInfo.firstName / lastName | string | Guest only | Guest name parts. |
registrationInfo.registrationFields.lookupFields | array | YES | Lookup 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:
| Code | Message |
|---|---|
7001 | A confirmed cashless user already exists and can not be added again |
9505 | Your password contains some weird combination, try another. |
6101 | Cannot 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_depositsorget.feature.enable_low_balance_auto_deposit.
Get the current settings
plaintext
POST /json/user
method: retrieveAutoDepositSettings| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | Current 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
}| Field | Meaning |
|---|---|
active | Whether auto-deposit is on. |
autoDepositType | 0 off, 1 time-based, 2 low balance. |
amount | Amount added on each run. |
lowBalanceAmount | Threshold for low-balance deposits. |
fromAccountId | Funding account (credit card or bill-me source). |
toAccountId | Destination account. |
dayOfWeek | 0–6 for weekly schedules (0 when monthly). |
dayOfMonth | 1–31 for monthly schedules (0 when weekly). |
Update the settings
plaintext
POST /json/user
method: updateAutoDepositSettings| Field | Type | Required |
|---|---|---|
userAutoDepositSettingInfo | object | YES |
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:
| Type | Frequency | Fields set |
|---|---|---|
| Time-based | Weekly | dayOfWeek set, dayOfMonth: 0 |
| Time-based | Monthly | dayOfMonth 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| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | Current user id. |
paymentType | number | YES | 1 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| Field | Type | Required |
|---|---|---|
userId | string | YES |
notification | object | YES |
notification:
| Field | Type | Description |
|---|---|---|
id | string | null | Id of the user's existing push notification record, or null on first registration. Taken from user.userNotificationInfoList (first entry with type = 8). |
type | number | Always 8 (PUSH_NOTIFICATION). |
value | string | FCM / APNs device token. |
provider | string | "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: logoutAndRemoveUserNotificationSame parameter shape. List all registrations with:
plaintext
POST /json/user
method: retrieveAllUserNotificationsjson
{
"method": "retrieveAllUserNotifications",
"params": { "userId": "{USER_ID}", "sessionId": "{SESSION_ID}" }
}