Link Bank Account

post/extensions/roboledger/{graph_id}/operations/link-bank-account

Point a bank feed's account at a chart account. Name element_id for an existing active account, or entity_id alone to create one in that entity's chart. The chart the account is in decides whose books the feed's lines go into, so this is also how a feed account is bound to a subsidiary. Lines still in the inbox move with it (across an entity change their suggestion is resolved again on the new chart, and a classification that named the old entity's account is dropped); posted entries stay where they were posted. An account another connection already feeds is refused, as is an entity whose books QuickBooks keeps (the group parent, while QuickBooks is connected). An account the feed created and then left stays on its chart as an ordinary account. A sync already in flight when the link moves can still land a line or two on the old account; running this again moves them. Read the group's accounts with the bankAccounts GraphQL field.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`connection_id`required	string	The feed's connection. Constraints: at least 1 character
`account_id`required	string	The provider's id for the account. Constraints: at least 1 character
`element_id`optional	string	The chart account to link; its chart's entity takes the feed.
`entity_id`optional	string	With `element_id`, the entity the account must belong to. Alone, the entity in whose chart a new account is created for the feed account.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/link-bank-account" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "string",
  "account_id": "string"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

LinkBankAccountResponse

Command-specific result payload

LinkBankAccountResponse fields

Field	Type	Description
`connection_id`required	string
`provider`required	string
`account_id`required	string
`element_id`required	string	The chart account the feed now books to.
`previous_element_id`required	string
`entity_id`required	string	The entity the feed's lines now belong to.
`account_created`optional	boolean	A new account was created in the entity's chart. Default: `false`
`events_repointed`optional	integer	Inbox lines moved to the new account (posted entries stay). Default: `0`
`events_unclassified`optional	integer	Lines returned to `captured`: their classification named an account in the previous entity's chart. Default: `0`
`pairs_across_entities`optional	integer	Open transfer pairs whose two legs now sit on two entities, because only one leg's account moved. Intercompany; the commit guard refuses them until the other leg follows. Default: `0`
`changed`optional	boolean	False when the link already stood and no line moved. Default: `true`

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error