Accounts

Accounts APIs retrieve and manage customer account information. An account is the contract between a customer and the financial institution (checking, savings, loan, line of credit, etc.).

End-user benefits

• Check account status and balance in real time.
• Drive intra-FI transfer recipient flows using accout lists.

Integration capabilities

• Retrieve accounts with ODATA $filter by id, nickname, type, account number, and category (DEPOSIT, LOAN, INVESTMENT, TIERED_LOAN, CROSS_USER_ACCOUNT).
• Return cross accounts by default; control detail with viewName and related query options.
• Use institutionCustomerId to look up accounts for a specific location (see the Get Customer Profile API for more details). This is specific to Business Banking users.

List Accounts and Get Account by ID

Response field filtering (viewname.external)

Responses are filtered to an allow-list from viewname.external. Omit query parameter viewName on list or single-account retrieval to return every top-level property in that list.

Default allow-list

id, institutionUserId, institutionCustomerId, institutionId, description, accountNumber, nickName, type, category, currentBalance, availableBalance, status, allowedActions, routingNumber, interestRate, interestYearToDate, micrNumber, maturityDate, term, escrowBalance, currentPrincipalBalance, nextPaymentAmount, nextPaymentDate, payOffAmount, calculatedPayOffAmount, minimumPayment, lineOfCreditLimit, loanOriginationDate, pastPrincipalDueDate, lastPrincipalPaymentAmount, originalLoanAmount, tpvReference, lastStatementBalance, primaryHolderName.

Scopes

Scope	Description
accounts:read	Read accounts

Required headers

Header	Description
Authorization	Bearer token (V2 authentication)
transactionId	Unique identifier for request tracking

Error codes (ACC_*)

Code	Message	HTTP Status Code
ACC_00002	Given password is invalid	401
ACC_00003	The account is invalid for summary display	500
ACC_00004	The account is hidden	500
ACC_00005	Error processing filter expression	400
ACC_00006	'From' Account restricted for transfer	500
ACC_00007	'To' Account restricted for transfer	500
ACC_00008	Invalid 'From' account status for transfer	500
ACC_00009	Invalid 'To' account status for transfer	500
ACC_00010	'From' Account has zero or negative balance	500
ACC_00011	Validation Error	400
ACC_00012	Data not found	404
ACC_00014	The CIF number is required, but was not found	500
ACC_00015	InstitutionId provided is invalid or blank	400
ACC_00016	InstitutionUserType provided is invalid or blank	400
ACC_00017	InstitutionCustomerId provided is invalid or blank	400
ACC_00018	InstitutionId from Query param and JWT do not match	400
ACC_00019	InstitutionUserType from Query param and JWT do not match	400
ACC_00020	InstitutionCustomerId from Query param and JWT do not match	400
ACC_00021	UserId provided is invalid or blank	400
ACC_00022	UserId from Query param and JWT do not match	400
ACC_00023	InstitutionUserId provided is invalid or blank	400
ACC_00024	InstitutionUserId from Query param and JWT do not match	400
ACC_00025	InstitutionUserRole provided is invalid or blank	400
ACC_00026	InstitutionUserRole from Query param and JWT do not match	400
ACC_00101	User not found	404
ACC_00113	Update nickname feature is not enabled	403
ACC_00114	Nickname field should not be empty	400
ACC_00115	Nick name update is disabled for Joint Accounts	403
ACC_00116	NickName length in request is greater than configured maximum length or Database column length	400
ACC_00117	Host update is done but exception occurred while updating the database	500
ACC_00118	Host update is done but exception occurred while inserting record to database	500
ACC_00119	Hide/show account feature is not enabled	403
ACC_00201	Account type ATYP not present in the account data	500
ACC_00202	Format error in generating formatted account id with mask configuration	500
ACC_00203	No USR value present in the Host Data	500
ACC_00204	ACHTYP is configuared as BLANK in FI config file	500
ACC_00205	ANUM information not provided by FI HOST	500
ACC_00206	No formatted account was produced by configuration	500
ACC_00207	Requested account type not found in FI configuration validAccountTypes	500
ACC_00208	MICR value not provided by FI host	500
ACC_00209	CIID Format configuration error	500
ACC_00210	EnableFormatter is not true for ACHTYPE CIID for FI	500
ACC_00211	Valid account types not set for Institution	500
ACC_00300	Utility DB is not available	500
ACC_00408	BB User is missing User Id in the request	400
ACC_00410	A location is required for BB users	400
ACC_00500	Requested service or feature is switched off	500
ACC_00501	Couchbase System is unavailable	500
ACC_00600	ServiceType parameter is invalid. Valid values are IB/BB	400
ACC_00601	Invalid JWT token	401
ACC_00602	Unauthorized access	401 or 403
ACC_00702	Subuser Id is empty	400
ACC_00704	InstitutionId is invalid or its incorrectly configured	500
ACC_00705	Member number is not valid.	500
ACC_88888	Internal validation error.	500
ACC_99988	Server can only handle JSON request. Other media types are not supported	415
ACC_99989	RequestBody size exceeds limit.	400
ACC_99990	Client error	400
ACC_99991	Request callingAppId header is too long	400
ACC_99992	One or more request query params are invalid or not provided.	400
ACC_99993	Server cannot handle this request	500
ACC_99994	Invalid query param	400
ACC_99995	Request should only contain printable ASCII characters	400
ACC_99996	Request header is too long	500
ACC_99997	Request transactionId header is too long	400
ACC_99998	Request is missing a transactionId header	400
ACC_99999	Error in Accounts Service	500

List Accounts (Legacy)

Required headers

Header	Description
Authorization	Bearer token (V1 authentication)
di_tid	Unique identifier for request tracking

Error codes

Code	Type	Message	HTTP Status Code
10001	SYSTEM_ERROR	Internal System Error.	500
10002	SYSTEM_ERROR	Connection Error.	500
10003	SYSTEM_ERROR	Configuration Error.	500
10006	SYSTEM_ERROR	Output validation error occurred	500
20009	APP_ERROR	PrincipalEndUser:Data not found.	404
25002	USER_ERROR	User Id or password is invalid	500
25099	USER_ERROR	Required HTTP Headers were not found	400
25134	SYSTEM_ERROR	Alt_mem_number required but not found in database	500
25401	APP_ERROR	Account type ATYP not present in the account data.	500
25502	APP_ERROR	Account formatter error	500
25503	APP_ERROR	No USR value present in the Host Data	500
25504	APP_ERROR	ACHTYP is configuared as BLANK in FI config file	500
25505	APP_ERROR	ANUM information not provided by FI host	500
25506	APP_ERROR	No formatted account was produced by configuration	500
25507	APP_ERROR	Requested account type not found in FI configuration validAccountTypes	500
25518	APP_ERROR	MICR value not provided by FI host	500
25519	APP_ERROR	CIID Format configuration error	500
25520	APP_ERROR	EnableFormatter is not true for ACHTYPE CIID in Fi config	500
25555	APP_ERROR	Requested service or feature is switched off	500
25612	APP_ERROR	Response from entitlements service is not successful	500
25615	SYSTEM_ERROR	Entitlement Service is temporarily unavailable	500
25618	USER_ERROR	Subuser auth ID is empty	500
25619	APP_ERROR	Mismatch of the data between the requested resource and response returning	500
25665	APP_ERROR	Extern format is not enabled/Invalid extern format	500
25673	APP_ERROR	HTTP Response from BB Entitlements Service is not successful	500
25674	SYSTEM_ERROR	BB Entitlement Service is temporarily unavailable	500
25679	APP_ERROR	The user is not entitled for view account(s)	500
25690	USER_ERROR	BB User is missing Auth ID Request Header	500
25693	APP_ERROR	Invalid User Type Header for Business Banking User	500
25694	APP_ERROR	Invalid User Type Header for IB User	500
25722	SYSTEM_ERROR	HTTP Response from Business Customer Service is not successful	500
25723	SYSTEM_ERROR	Business Customer Service is temporarily unavailable	500
25736 / 25737	USER_ERROR	Invalid member number	500
28001	SYSTEM_ERROR	Circuit Breaker HardTrip configuration set to true in FI config file	503
28002	SYSTEM_ERROR	Circuit Breaker Status is Open	503
28003	SYSTEM_ERROR	Incoming requests count exceeded configured Semaphore count	503
50000	SYSTEM_ERROR	Internal error in downstream	500
Host Code	-	Host Message	500

Retrieve Customer Accounts with Transactions

Scopes

Scope	Description
accounts:read	Read accounts
transactions:read	Read transactions

Required headers

Header	Description
Authorization	Bearer token (V2 authentication)
correlationId	Unique identifier for request tracking

Error codes (UXU_*)

Code	Message	HTTP Status Code
UXU_10002	Required role not present in JWT token	403
UXU_10003	JWT token has expired	400
UXU_10004	JWT token is invalid, does not contain institution id	400
UXU_10005	Required Authorization header is missing	400
UXU_10006	Required Correlation Id header is missing	400
UXU_10007	Correlation Id is not a GUID	400
UXU_10008	Invalid IP address in the header	400
UXU_10009	Invalid Authorization in the header	400
UXU_10010	JWT token is invalid, does not contain institution customers id	400
UXU_10011	JWT token institution customers id is not matching customer id path param	400
UXU_30001	Error interacting with the service	500 or 503
UXU_30002	Error interacting with the external service	500 or 503
UXU_88888	No entitled customers found	404

Endpoints

Get Account by ID

Returns detailed information for a specific financial account that the authenticated user

List Accounts

Returns a list of financial accounts that the authenticated user is entitled to access.

List Accounts (Legacy)

Retrieves account information for a specified financial institution customer, including

Retrieve Customer Accounts with Transactions

Returns a unified view of a customer’s accounts with embedded transactions by aggregating