Bank Teller
Sign In
Back to About

API Reference

All API calls go through the Next.js proxy (/api/* → teller_api_dev:5200). Every request requires a valid Keycloak Bearer token. Role requirements are shown where they differ from the default (any authenticated user).

GETPOSTPUTPATCHDELETEHTTP method key
🏢

Branch & Session

Controls the branch's operating state. A branch must be Open before a session or vault can be started.

GET
/branch

Get current branch status and open/close times

POST
/branch/open

Open the branch for the business day

BranchManager
POST
/branch/close

Close the branch at end of day

BranchManager
POST
/branch/force-close

Emergency close with mandatory reason

BranchManager
GET
/session

Get the active business session

POST
/session/open

Initiate dual-control session open — returns 202 + BranchOpen approval

HeadTeller+
POST
/session/activate

Activate session after teller proof-ins reviewed (Open → Active)

Supervisor+
GET
/session/slot/:slot

Get the session record for a specific slot (Single/Morning/Evening)

POST
/session/close

Close the session at end of day

🔒

Vault

All vault operations require dual-control: a Supervisor or HeadTeller initiates, and a BranchManager (or vice-versa) approves. Returns a pending approval — not an immediate result.

GET
/vault

Get vault status and current cash balances

POST
/vault/open

Initiate vault opening with denomination counts

Supervisor+
POST
/vault/close

Initiate vault closing

Supervisor+
POST
/vault/transfer-in

Initiate cash movement into the vault

Supervisor+
POST
/vault/transfer-out

Initiate cash movement out of the vault

Supervisor+
POST
/vault/report-discrepancy

Report a vault cash discrepancy — creates pending VaultDiscrepancyReconciliation approval

Supervisor+
🗂️

Approvals

The dual-control queue. Every vault or drawer operation creates a pending approval that a second authorized officer must review.

GET
/approvals

List pending approvals for this branch (?pendingOnly=false for full history)

GET
/approvals/:id

Get a single approval by ID

POST
/approvals/:id/approve

Approve a pending action — executes immediately

Supervisor+
POST
/approvals/:id/reject

Reject a pending action

Supervisor+
💼

Teller Drawer

Each teller has one drawer. Opening requires the teller to be on today's roster. All balances must reach zero before the drawer can be closed (zero-carryover rule).

GET
/drawer

Get the caller's active drawer with balances and transactions

GET
/drawer/all

List all open drawers in the branch

Supervisor+
GET
/drawer/peers

List other drawers available for teller-to-teller exchange

POST
/drawer/open

Open a drawer with initial denomination counts (requires roster entry)

POST
/drawer/close

Close the drawer — rejected if any balance ≠ 0

POST
/drawer/transfer-to-vault

Initiate cash transfer from drawer to vault (dual-control)

POST
/drawer/transfer-from-vault

Initiate cash transfer from vault to drawer (dual-control)

POST
/drawer-rebalance

Submit mid-day drawer denomination count — 200 (HeadTeller+ unilateral) or 202 (pending Supervisor approval)

Teller+
💳

Transactions

Core banking operations posted through the ESB. Tellers are subject to OPA cash limits per currency; transactions above the threshold are routed to the async dual-control approval queue.

GET
/transactions

List all transactions in the current drawer session

POST
/transactions/deposit

Post a cash deposit to a customer account

POST
/transactions/deposit/pending

Submit an over-limit deposit for supervisor approval — returns 202 + BranchApproval

POST
/transactions/withdrawal

Post a cash withdrawal from a customer account

POST
/transactions/withdrawal/pending

Submit an over-limit withdrawal for supervisor approval — returns 202 + BranchApproval

POST
/transactions/cheque-deposit

Post a cheque deposit

POST
/transactions/:id/reverse

Reverse a previously posted transaction

POST
/transactions/exchange

Perform a foreign currency exchange

POST
/transactions/exchange/internal

Internal currency exchange between teller or vault

POST
/transactions/transfer/own

Transfer between a customer's own accounts

POST
/transactions/transfer/local

Transfer to a third-party IBAN

🔑

Supervisor Override

When a transaction exceeds the teller's cash limit, a supervisor must authorize it in real-time. The resulting token is single-use with a 5-minute TTL.

POST
/supervisor/authorize

Issue a time-limited override token for high-value transactions

Supervisor+
🚨

Force Close

Emergency close operations that bypass all state and balance checks. Dual-control routing is determined by the ApprovalPolicies table — most specific rule wins by priority.

POST
/vault/force-close

Force-close the vault with optional discrepancy record

Supervisor+
POST
/drawer/force-close/:drawerId

Force-close a teller drawer — initiator rank must exceed drawer owner

Supervisor+
POST
/session/force-close

Force-close today's business session

BranchManager+
📋

Teller Proof-In

Per-teller start-of-day cash-box count. Each teller submits denomination counts compared against their last closed drawer balance.

POST
/teller-proof-in

Submit teller cash-box denomination counts — returns Matched or creates Mismatched pending approval

Teller
GET
/teller-proof-in/status

Get the current proof-in status for the calling teller

Teller
GET
/teller-proof-in/branch-status

Get all teller proof-in statuses for the branch (supervisor review)

Supervisor+
POST
/teller-system-proof

MBT terminal sign-in or sign-out — gates drawer open via HasProofedIn

Teller
GET
/teller-system-proof/status

Get today's MBT terminal system proof status (ProofInAt, ProofOutAt)

Teller
📥

Vault Proof-In

Start-of-day physical cash count submission by ICD Officers. System computes variance against vault opening balance.

POST
/proof-in

Submit physical cash counts for all currencies — Matched or creates pending Mismatched approval

IcdOfficer
GET
/proof-in/status

Get the current proof-in status for the branch business day

IcdOfficer
📤

Proof-Out

End-of-day physical cash count. Two custodians must independently submit counts; the second triggers reconciliation against live vault balances. Matched status required before vault close.

POST
/proof-out

Submit EOD physical cash counts — first custodian sets AwaitingBothCustodians; second triggers reconciliation

IcdOfficer
GET
/proof-out/status

Get proof-out status with custodian names and submitted counts

IcdOfficer
🚨

Counterfeit Reports

Tellers submit a counterfeit currency report when fake notes are detected. Each report creates a BranchManager review approval.

POST
/counterfeit-reports

Submit a counterfeit report — creates CounterfeitReportBmReview pending approval

Teller
GET
/counterfeit-reports

List all counterfeit reports for the branch

🏦

Cash Orders (Bait Al Mal)

Request a cash transfer to or from the branch. Two order types: CTB (Cash Transfer to Branch) and CFB (Cash From Branch). Blocked after the cutoff time.

POST
/cash-orders

Submit a cash order — blocked after GST cutoff (Standard 15:00 / Mall 21:00); creates CashOrderBmApproval pending approval

HeadTeller+
GET
/cash-orders

List all cash orders for the branch

📋

Pending Admin Changes

Maker-checker queue for ICD Officer admin mutations. Changes are queued for ICD Manager review instead of being applied immediately.

GET
/admin/pending-changes

List pending admin changes — IcdOfficer read-only view; IcdManager+ can approve/reject

IcdOfficer+
POST
/admin/pending-changes/:id/approve

Approve and execute a pending configuration change — self-approval blocked

IcdManager+
POST
/admin/pending-changes/:id/reject

Reject a pending change with optional reason

IcdManager+
⚙️

Admin

Configuration endpoints. All requests are China-Wall scoped — EntityAdmin sees own entity, BankAdmin sees all. Key mutations are gated by admin.MenuAccessMatrix.

GET
/admin/users

List Keycloak users for your entity

BranchManager
POST
/admin/users

Create a new Keycloak user with role and bank attributes

BranchManager
PUT
/admin/users/:id

Update a user's role, entity, or branch assignment

BranchManager
POST
/admin/users/:id/reset-password

Reset a user's Keycloak password

BranchManager
DELETE
/admin/users/:id

Remove a user from Keycloak

BranchManager
GET
/admin/roster

List teller roster entries for a branch and date

POST
/admin/roster

Add a teller to the roster for a specific date

DELETE
/admin/roster/:id

Remove a roster entry

GET
/admin/business-days

List business days for a branch in a date range

POST
/admin/business-days

Register a new business day

GET
/admin/cash-limits

Get cash limits per currency for your entity

PUT
/admin/cash-limits

Set the cash limit for a currency — auto-syncs to OPA

GET
/admin/opa/policy

Get the current live Rego policy from OPA

PUT
/admin/opa/policy

Update the Rego policy — takes effect immediately

BankAdmin
POST
/admin/opa/sync

Force-push DB cash limits to OPA

BankAdmin
GET
/admin/approval-policies

List data-driven approval routing policies

BranchManager+
POST
/admin/approval-policies

Create a new approval policy rule

BranchManager+
PUT
/admin/approval-policies/:id

Update an approval policy rule

BranchManager+
DELETE
/admin/approval-policies/:id

Delete an approval policy rule

BranchManager+
GET
/admin/custodians

List vault custodian status for all active roster entries

IcdOfficer+
PUT
/admin/roster/:id/custodian

Designate or revoke vault custodian flag for a roster entry

IcdOfficer+
GET
/admin/drawer-limits

List drawer balance limits per currency for a branch

BranchManager
PUT
/admin/drawer-limits

Upsert drawer balance limit — HardBlock or EscalateToApproval

BranchManager
GET
/admin/exchange-rates/local

List local exchange rates used for AGG calculations

BranchManager
PUT
/admin/exchange-rates/local

Upsert a local exchange rate — write requires Entity Admin

EntityAdmin
GET
/access-matrix

Get the caller's menu access matrix (multi-role OR semantics)

GET
/admin/access-matrix

Get full access matrix for an entity (all roles, all menu keys)

IcdOfficer
PUT
/admin/access-matrix

Upsert a single Role+MenuKey permission row

IcdOfficer
GET
/admin/holidays

List public holidays for an entity/branch within a date range

BranchManager+
POST
/admin/holidays

Create a public holiday (entity-wide or branch-specific)

BranchManager+
PATCH
/admin/holidays/:id

Rename a public holiday

BranchManager+
DELETE
/admin/holidays/:id

Delete a public holiday

BranchManager+
PATCH
/admin/entities/:entity/weekend-days

Set weekend days for all branches in an entity

BranchManager+
PATCH
/admin/branches/:branchId/weekend-days

Set weekend days for a single branch

BranchManager+