Skip to main content

Register an account

POST 
/v1/accounts

Register one of your bank's core banking system (CBS) accounts with the Lyriq Connector for a root settlement asset, so that it can be used in transfers and position reads.

Required scope: connector:accounts:create.

What happens. The request is validated and, if accepted, the Lyriq Connector creates an asynchronous operation and returns 202 Accepted with that operation. The operation first waits in PENDING_REVIEW for one approval by a user with the approver role in your bank (see Reviews). After approval the platform opens the ledger account and maps it to your external_account_id.

When the account is usable. Poll GET /v1/operations/{operation_id} (the URL in data.links.self; this response carries no Location header) until the state is terminal. Once it is SUCCEEDED the account can be read at the URL in data.relationships.resource.links.related, which is /v1/accounts/{external_account_id}?asset_id={asset_id} with external_account_id percent-encoded. Before that, GET on that URL returns 404 Not Found.

Identity. An account is identified by your bank, asset_id and external_account_id. The JSON:API id of the future account is returned in data.relationships.resource.data.id and is derived deterministically as v1:{bank_id}:{asset_id}:{external_account_id} with each component percent-encoded (see the Account schema for a worked example).

Duplicates and retries. The Idempotency-Key header is required. Repeating the request with the same key and the same body returns the original 202 response without registering again; the same key with a different body returns 409 Conflict (IDEMPOTENCY_CONFLICT), and a retry while the first request is still being processed returns 409 Conflict (IDEMPOTENCY_PENDING). Registering an account that already exists (same asset_id and external_account_id) under a new key returns 409 Conflict with title account already exists.

Validation. Errors are returned before anything is created:

  • external_account_id empty: 400, code MISSING_FIELD.
  • external_account_id longer than 34 characters or containing a character not allowed in XML 1.0: 400, code INVALID_FIELD_FORMAT.
  • asset_id empty or whitespace: 400, code MISSING_FIELD.
  • display_name present but blank: 400.
  • Unknown attribute, wrong type or missing required attribute in the body: 422 Unprocessable Entity.
  • Your bank is not ACTIVE: 400 with title Invalid bank: the owning bank does not exist or is not active.
  • asset_id is not enabled for your bank: 400 with title the requested asset is not in bank {bank_id}'s enabled set.

Request​

Responses​

Registration accepted. The body is the operation that tracks it; its relationships.resource identifies the account that will exist once the operation succeeds.