UDA endpoints — accounts

How to call the accounts routes. The formal schema is the OpenAPI specification (openapi/source/connector/accounts/); this page is the call contract. Internal processing is in the architecture reference; caveats in the implementation notes.

All routes require a bearer token and party context (partyId), which the connector uses to resolve the customer in ULTRACS. accountId in the path is the Ark account id.

Method	Path	Code	Purpose
GET	/v1/accounts	200	List the party's accounts
GET	/v1/accounts/{accountId}	200	Account detail
POST	/v1/accounts	201	Open a savings account
PUT	/v1/accounts/{accountId}/alias	204	Set the account nickname
GET	/v1/accounts/{accountId}/transactions	200	List transactions
GET	/v1/accounts/{accountId}/transactions/{transactionId}	200	Transaction detail
GET	/v1/accounts/{accountId}/signatories	200	List signatories
POST	/v1/accounts/{accountId}/signatories	201	Add a signatory
DELETE	/v1/accounts/{accountId}/signatories/{partyId}	204	Remove a signatory

Notes for callers

• Create (POST /v1/accounts) takes productKey + productVersion (resolved against the local product catalogue), optional requiredSignaturesForPayment (default 1) and callerIsSignatory (default true). It opens a savings account; funding source and share type are fixed by the connector.
• transactionId values are opaque encrypted handles returned by the transactions list — pass them back verbatim to the detail route. A handle for a PENDING transaction changes once the transaction posts (see the implementation notes).
• Add signatory takes the target partyId, a relationshipCode (AUTHORISED_SIGNATORY / POWER_OF_ATTORNEY / TRUSTEE / OFFICE_HOLDER are supported; others are rejected), optional signatory (default true) and statementMethod (default ELECTRONIC). See the relationship map in the architecture reference.
• Remove signatory refuses to remove the last active signatory of an account (409).

Errors

HTTP	Code	When
400	GEN000000	request body/params fail schema validation
401	ACC001001	the account isn't owned by the caller's client (via AccountsRepository.getClientKey)
404	PAR004001	no party mapping for the caller (ClientAuthManager.getClientKey → PARTY_NOT_FOUND)
404	ACC004001	no account mapping for accountId
404	ACC004003	POST create: product not found in the catalogue
409	ACC009001	alias: ULTRACS reports the alternative name cannot be edited
409	ACC009002	delete signatory: would remove the last active signatory
500	ACC100004/5/6/7	invalid account details / missing ULTRACS number / unknown transaction code / unsupported relationship type
500	GEN100001	an ULTRACS fault with no mapping (handleUltracsError falls back to DOWNSTREAM_CONNECTOR_ERROR; esp. all signatory faults — see the implementation notes)