Skip to content

Mobile Access ​

Service path: /json/commerce

Mobile Access turns the phone into a door credential. The patron app lists the doors ("locations") the user can open, and activating one returns either a PDF417 barcode, a temporary code, or both, plus a validity countdown.

NOTE

Both methods are flagged useSessionId = true and useInstitutionId = false, so only sessionId is injected.

List locations ​

Returns the doors available to the current user, nearest first.

plaintext
POST /json/commerce
method: getMobileLocations
FieldTypeRequiredDescription
filtersstring[]YES["Normal", "TempCode", "Attendance"] in the app.
latitudenumber | nullYESDevice latitude.
longitudenumber | nullYESDevice longitude.
accuracynumber | nullNOLocation accuracy in metres.
sessionIdstringYESInjected.
json
{
    "method": "getMobileLocations",
    "params": {
        "filters": ["Normal", "TempCode", "Attendance"],
        "latitude": 43.073052,
        "longitude": -89.40123,
        "accuracy": 12,
        "sessionId": "{SESSION_ID}"
    }
}

The filter values map to the three kinds of access point:

FilterMeaning
NormalStandard door readers.
TempCodeReaders that issue a short-lived numeric code.
AttendanceAttendance / time-clock readers.

Response is an array of locations. The app reads locationId, name, distance, and score:

json
{
    "response": [
        {
            "locationId": "{LOCATION_ID}",
            "name": "Student Union — East Entrance",
            "type": "Normal",
            "distance": 84.2,
            "color": "#0099cc",
            "score": 5
        },
        {
            "locationId": "{LOCATION_ID}",
            "name": "Library — Loading Dock",
            "type": "TempCode",
            "distance": 220.7,
            "color": "#0099cc",
            "score": 1
        }
    ],
    "exception": null
}
FieldMeaning
locationIdDoor id; used to activate it and to store favorites.
nameDisplay name.
typeOne of the three filter values.
distanceDistance from the supplied coordinates (metres; converted to miles in the UI).
colorPresent in the payload, but the app does not read it — the list is coloured by CSS.
scoreServer-side relevance/priority ranking.

Sorting and favorites ​

The client sorts the response itself:

  1. Favorites first.
  2. Then by descending score.

Favorites are not a server list. The app stores an array of locationId strings in the user setting mobileaccess_favorites (via /json/user retrieveSetting / saveSetting). Toggling a star rewrites that setting; no rewards/access endpoint is called.

Activate a location ​

Opens a door, or issues a code/barcode for it.

plaintext
POST /json/commerce
method: activateMobileLocation
FieldTypeRequiredDescription
locationIdstringYESDoor id from getMobileLocations.
tranDatestringYESISO-8601 timestamp (the app sends new Date().toISOString()).
latitudenumber | nullNODevice latitude (null if unavailable).
longitudenumber | nullNODevice longitude.
accuracynumber | nullNOAccuracy in metres.
altitudenumber | nullNOAltitude.
altitudeAccuracynumber | nullNOAltitude accuracy.
speednumber | nullNODevice speed.
headingnumber | nullNODevice heading.
sourceInfostring | nullNOFree-form source tag. The app sends null.
sessionIdstringYESInjected.
json
{
    "method": "activateMobileLocation",
    "params": {
        "locationId": "{LOCATION_ID}",
        "tranDate": "2026-11-19T14:03:22.145Z",
        "latitude": 43.073052,
        "longitude": -89.40123,
        "accuracy": 12,
        "altitude": null,
        "altitudeAccuracy": null,
        "speed": null,
        "heading": null,
        "sourceInfo": null,
        "sessionId": "{SESSION_ID}"
    }
}

Response ​

json
{
    "response": {
        "message": "Door unlocked",
        "responseCode": "00",
        "showBarCode": 1,
        "showTempCode": 1,
        "validityTime": 30,
        "issuedCode": "0123456789012345678901234567890123456789"
    },
    "exception": null
}
FieldMeaning
messageHuman-readable result shown in the dialog.
responseCode"00" = success. Any other value is treated as an error.
showBarCode1 = render a PDF417 barcode from issuedCode.
showTempCode1 = display issuedCode as a numeric code.
validityTimeSeconds the code is valid; drives the countdown timer.
issuedCodeThe payload: barcode data and/or the temporary code.

Result handling ​

The app decides what to display from the two show* flags:

showBarCodeshowTempCodeUI
11Barcode dialog (PDF417, includetext: false) plus the countdown.
any1Numeric code dialog plus the countdown.
00Success dialog with message only.

The barcode is rendered client-side as PDF417 from issuedCode. The countdown uses validityTime; when it expires the dialog closes. If barcode rendering throws, the app shows the error.barcode_render toast.

responseCode is compared as a string, so "00" succeeds and "0" does not.

Error handling ​

ConditionBehavior
responseCode !== "00"Error dialog titled with the error content string; message is shown verbatim.
message contains enable location servicesTreated as a location-services failure (the user is prompted to enable GPS).
Transport/exception errorToast mobile-access toast_activate-response-error.

Flow summary ​

  1. Request location permission.
  2. getMobileLocations with the device coordinates.
  3. User picks a door (favorites pinned to the top).
  4. activateMobileLocation with the current coordinates and timestamp.
  5. If responseCode === "00", show the barcode/code dialog for validityTime seconds.

The disclosure screen shown before the first activation is content category patron-ui.location_disclosure_screen.

  • Commerce — accounts, deposits, and the rest of /json/commerce.
  • Reference — patron/openmydoor route.