System Task API

System task endpoints expose data that is institution-scoped rather than user-scoped: the list of every institution available in CBORD GET, per-institution metadata, photos, feature flags, SOA encoding keys, and mobile credentials.

These endpoints don't use a user session — they use a system session token. A system session is a UUIDv4 obtained by authenticating with hard-coded systemCredentials rather than device_id/pin. The wrapper does this for you when you hit /api/v2/system/auth.

IMPORTANT

The session_id accepted by every endpoint on this page is a system session token, not the user-session token returned by /api/v2/auth. The two token types are minted by different CBORD methods (authenticateSystem vs authenticatePIN) and are not interchangeable.

TIP

System sessions don't need device_id or pin to renew — the wrapper just calls authenticateSystem again. So auto_renew_session on these endpoints requires no extra credentials.

Create / Validate System Session

Mints a new system session, or echoes back the provided one if still valid.

POST /api/v2/system/auth

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	NO	If provided and still valid, the same session_id is returned. Otherwise a brand new one is minted via authenticateSystem. Pass null, "getNewSession", or omit to force a new session.

Success Response

{
    "response": "{SYSTEM_SESSION_ID}",
    "exception": null
}

Details

This endpoint does not participate in the auto_renew_session flow — it is the renewal mechanism. Repeated calls won't close prior system sessions automatically; use /api/v2/system/closeSession if you need to retire one.

Validate System Session

Checks whether a system session_id is still valid without minting a new one on failure.

POST /api/v2/system/validate

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	System session token to validate.

Success Response

{ "session_valid": true }

Failure Response

{ "session_valid": false }

NOTE

Internally this probes the lightest system-scoped CBORD call available (institution.retrieveLookupList) and treats a non-null exception (e.g. 4001|Session not found) as invalid. CBORD's authenticateSessionToken method is not used for validation here — empirically it returns {"response":"","exception":null} for any input, so it cannot distinguish valid from invalid sessions.

Close System Session

Force-closes a system session_id.

POST /api/v2/system/closeSession

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	System session token to close.

Success Response

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

Auto-Renew Behavior For System Task Endpoints

Every endpoint below this point accepts the standard auto-renew parameters. Because system sessions don't require device_id or pin to renew, the wrapper only needs your existing (or missing) token and the boolean opt-in flag.

Body Parameters	Type	Required	Description
session_id	string	YES (unless auto_renew_session=true and you want the wrapper to mint one)	System session token.
auto_renew_session	boolean	NO	Set true to have the wrapper validate session_id and silently mint a new one if it's expired or missing.

When auto_renew_session is true, every successful response includes an autoRenewConfig key alongside response:

{
    "response": ...,
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": true,
        "token": "{SYSTEM_SESSION_ID_USED}"
    }
}

• sessionIdChanged — true if the wrapper minted a new session; false if your supplied session_id was still valid.
• token — the session token that actually fulfilled the request. Save this for reuse.

IMPORTANT

Unlike the user-session counterpart, this auto-renew flow requires no extra body parameters (no device_id, no pin). The error code WA001 from the commerce/user endpoints does not apply here. If renewal itself fails, you'll get WA005 instead (see Common Errors).

Get All Institutions

Lists every institution available in the CBORD GET system. Backed by institution.retrieveLookupList.

POST /api/v2/system/getInstitutions

Request Parameters

See Auto-Renew Behavior for session_id / auto_renew_session.

Success Response

{
    "response": [
        {
            "id": "{INSTITUTION_ID_UUID_V4}",
            "name": "{INSTITUTION_NAME}",
            "shortName": "{INSTITUTION_SHORT_NAME}",
            "type": 0
        }
    ],
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

NOTE

The shape and keys returned in each entry are passed through from CBORD. Field coverage varies — schools may include or omit certain fields depending on how the institution is configured.

Get Institution Details

Returns the full detail record for one institution. Backed by institution.retrieve.

POST /api/v2/system/getInstitution

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution to retrieve.
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": {
        "id": "{INSTITUTION_ID_UUID_V4}",
        "name": "{INSTITUTION_NAME}",
        "shortName": "{INSTITUTION_SHORT_NAME}",
        "type": 0
    },
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

NOTE

response.type appears to be 0 for schools and 1 for hospitals/medical locations, though the full enum is not documented by CBORD.

Failure Response

WA006: Missing institution_id

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

Get Institution Photo

Retrieves the institution photo. Backed by institution.retrieveInstitutionPhoto.

POST /api/v2/system/getInstitutionPhoto

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution.
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": {
        "id": "{PHOTO_ID}",
        "mimeType": "image/png",
        "data": "{BASE64_ENCODED_IMAGE}"
    },
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

NOTE

Exact response shape is passed through from CBORD. The image payload is base64-encoded in response.data (or equivalent field — confirm against your institution's response).

Failure Response

WA006: Missing institution_id

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

Get Institution Features

Returns the full list of feature flags configured for an institution. Backed by configuration.retrieveSettingList with category=feature, domain=get.

POST /api/v2/system/getInstitutionFeatures

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution.
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": [
        {
            "id": "{SETTING_ID}",
            "name": "enable_mobile_pin_entry",
            "domain": "get",
            "category": "feature",
            "contentMediaType": 1,
            "value": "true",
            "description": "..."
        }
    ],
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

Failure Response

WA006: Missing institution_id

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

Get Single Institution Feature

Returns one named feature flag for an institution. Useful for checking availability of a specific feature (e.g. mobile PIN entry) without pulling the whole list. Backed by configuration.retrieveSetting with category=feature, domain=get.

POST /api/v2/system/getInstitutionFeature

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution.
feature_name	string	YES	Name of the feature flag (e.g. enable_mobile_pin_entry).
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": {
        "id": "{SETTING_ID}",
        "name": "enable_mobile_pin_entry",
        "domain": "get",
        "category": "feature",
        "contentMediaType": 1,
        "value": "true",
        "description": "..."
    },
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

Failure Response

WA007: Missing institution_id or feature_name

{
    "response": null,
    "exception": "WA007: institution_id and feature_name are required",
    "exceptionCode": "WA007"
}

Get Institution SOA Key

Retrieves an institution's SOA encoding key — used by GET Mobile to compute SOA barcodes for cashless transactions. Backed by configuration.retrieveSetting with category=general, domain=soa, name=key.

POST /api/v2/system/getInstitutionSOAKey

TIP

This is the system-task equivalent of the legacy /api/v2/getInstitutionKey endpoint. The legacy endpoint always mints a new system session on every call; this one lets you reuse a system session, which is cheaper if you're already making multiple system task requests.

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution.
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": {
        "id": "{SETTING_ID}",
        "name": "key",
        "domain": "soa",
        "category": "general",
        "contentMediaType": 1,
        "value": "{ENCODING_KEY}",
        "description": "SOA institution encoding key. ex: A1B2C3D4E5F601020910"
    },
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

Failure Response

WA006: Missing institution_id

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

Get Institution Mobile Credentials

Returns the list of mobile credential settings (API keys, integration tokens, etc.) configured for an institution. Backed by configuration.retrieveSettingList with category=mobile_credentials, domain=get.

POST /api/v2/system/getInstitutionMobileCredentials

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES (or auto-renew)	System session token.
institution_id	string	YES	UUIDv4 of the institution.
auto_renew_session	boolean	NO	See Auto-Renew Behavior.

Success Response

{
    "response": [
        {
            "id": "{SETTING_ID}",
            "name": "{CREDENTIAL_NAME}",
            "domain": "get",
            "category": "mobile_credentials",
            "contentMediaType": 1,
            "value": "{CREDENTIAL_VALUE}",
            "description": "..."
        }
    ],
    "exception": null,
    "autoRenewConfig": {
        "sessionIdChanged": false,
        "token": "{SYSTEM_SESSION_ID}"
    }
}

Failure Response

WA006: Missing institution_id

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

Common Errors

WA005: System session renewal failed

Returned when auto_renew_session=true, the supplied session_id was invalid (or missing), and the wrapper's call to authenticateSystem itself also failed. The raw CBORD response is included as cbordResponse for debugging.

{
    "response": null,
    "exception": "WA005: Unable to renew system session",
    "exceptionCode": "WA005",
    "cbordResponse": { ... }
}

WA006: institution_id is required

{
    "response": null,
    "exception": "WA006: institution_id is required",
    "exceptionCode": "WA006"
}

WA007: institution_id and feature_name are required

{
    "response": null,
    "exception": "WA007: institution_id and feature_name are required",
    "exceptionCode": "WA007"
}