--- title: "Connect feeds to Xero Bank Accounts that already exist" method: POST path: "/FeedConnections/ExistingAccount" tags: ["FeedConnections"] --- # Connect feeds to Xero Bank Accounts that already exist `POST /FeedConnections/ExistingAccount` ## Request - Base URL: `https://api.xero.com/bankfeeds.xro/2.0` - URL: `https://api.xero.com/bankfeeds.xro/2.0/FeedConnections/ExistingAccount` - Auth: OAuth 2 - Authorization code: `https://login.xero.com/identity/connect/authorize` - Token URL: `https://identity.xero.com/connect/token` scopes: `bankfeedsv2` Creates Feed Connections against Xero Bank Accounts the Organisation already has. Each item must include the `accountId` of the account it connects to. Xero performs no matching of its own, and `accountNumber` and `accountName` are ignored if supplied. Use this endpoint whenever the customer has chosen an account, including when they are reconnecting a feed that was previously terminated. Each item is processed independently, and the response has one result per request item in request order. ## Headers - `Xero-Tenant-Id` string, required ## Request body - ExistingAccountFeedConnectionsRequest - `items` ExistingAccountFeedConnection[], required: Between 1 and 50 Feed Connections to create. No element may be null. - `accountId` string, uuid, required: The Xero Bank Account to connect the feed to. Required. An all-zeros GUID is treated as though the field were absent. - `accountToken` string, required: The financial institute's identifier for the account. Must be unique within your financial institute. Some financial institutes additionally constrain its format. - `accountType` 'BANK' | 'CREDITCARD', required: The high-level type of the account. `BANK` covers every account type other than a credit card. - `currency` string, required: ISO-4217 currency code. Must match the currency of the Xero Bank Account named by `accountId`, and must be a currency the Organisation has. - `country` string: ISO-3166 alpha-2 country code. Required only when the Application supports multiple regions. Talk to your Partner Manager to confirm whether this applies to you. - `accountNumber` string: Ignored. Taken from the Xero Bank Account named by `accountId`. - `accountName` string: Ignored. Taken from the Xero Bank Account named by `accountId`. ## Response `200` All items are 2xx: each one reached its desired state, and there is nothing left for you to do. A created item has `status` `SUCCESS` and `statusCode` `201`. A response that mixes successful items with rejected or partially failed ones is a `207`, not a `200`. - BulkFeedConnectionResponse: One result per request item, in request order. - `items` BulkFeedConnectionResult[] - `id` string, uuid: On a create, Xero's identifier for the new Feed Connection; absent when the item was rejected, since nothing was created. On a termination, the identifier supplied in the request, echoed back; absent only when the item did not include a usable identifier. - `accountToken` string: The `accountToken` supplied in the request, echoed back, including on a rejected item. Not returned on a termination. - `status` 'SUCCESS' | 'REJECTED' | 'PARTIAL_FAILURE': `SUCCESS` means the item reached the state the request asked for — on a create the connection exists, on a termination it is gone, including the idempotent case where it was already gone. `REJECTED` means nothing was written, or Xero confirmed that nothing took effect. A `4xx` item needs correcting before it is sent again, and a `500` item can be resent as it is. `error` says why. `PARTIAL_FAILURE` means the item did not complete, and the state it left behind needs attention or could not be confirmed. `error.subtype` says which, `error.detail` describes it, and the item needs attention that neither of the other two values implies. A client deserialising this into a closed set of `SUCCESS` and `REJECTED` will fail on `PARTIAL_FAILURE`. That is intended rather than an oversight: binding it silently to either of the other two would hide state that the partner has to act on. - `statusCode` integer: The numeric status of this item: `201` on a created connection, `204` on a terminated or already-absent one, a 4xx on a rejection, `500` on a partial failure or on a rejection whose error is `internal-error` or `too-many-requests`. The response envelope is computed from the items' `statusCode` values: all 2xx is `200`, all 4xx is `400`, anything else is `207`. So a partner can size up one item without reading `status` and `error` together. Never `202` and never `207`: those are envelope-only, and an item-level `207` would be numerically inside 2xx, so a batch of partial failures could be reported as `200`. - `error` ItemError: The `error` of an item result. It has the same fields as `Problem`, except `status`: the item's own `statusCode` is its HTTP status, so it is not repeated here. - `type` 'invalid-request' | 'invalid-application' | 'suspended-or-terminated-application' | 'invalid-organisation-bank-feeds' | 'invalid-organisation-multi-currency' | 'invalid-feed-connection-for-organisation' | 'invalid-user-role' | 'invalid-account-token' | 'missing-identifying-fields' | 'invalid-country-specified' | 'account-not-valid' | 'feed-already-connected-in-current-organisation' | 'account-name-already-exists' | 'bank-feed-not-found' | 'feed-not-found-or-already-deleted' | 'partial-failure-new-account-creation' | 'partial-failure-previous-connection-deletion' | 'partial-failure-connection-creation' | 'partial-failure-connection-deletion' | 'partial-failure-new-account-existence-not-confirmed' | 'too-many-requests' | 'internal-error': Identifies the error. - `subtype` 'connection-phase-failed' | 'deletion-phase-failed' | 'deletion-phase-not-confirmed' | 'connection-existence-not-confirmed' | 'connection-exists-without-feed-connection' | 'feed-connection-existence-not-confirmed-can-check-or-retry' | 'check-accounts-or-prompt-user-retry': Present only on a partial failure (a `partial-failure-*` `type`). Names the exact cause within the `type`. Reading it is optional: the `type` alone fixes the recovery action and which identifier fields are present, so branch on `type` and use `subtype` for diagnostics. - `title` string: A short human-readable summary of the error. - `detail` string: A human-readable explanation specific to this occurrence. - `accountId` string, uuid: Present only on a partial failure. The Xero Bank Account the item concerns. On `partial-failure-new-account-creation`, the account that was created: connect it through `POST /FeedConnections/ExistingAccount`. On `partial-failure-previous-connection-deletion` and `partial-failure-connection-creation`, the account being connected. Absent on `partial-failure-connection-deletion` and `partial-failure-new-account-existence-not-confirmed`, where the account may not exist. - `accountName` string: Present only on a partial failure of type `partial-failure-new-account-creation` or `partial-failure-new-account-existence-not-confirmed`. The name of the account that was created, which is now taken; on `partial-failure-new-account-existence-not-confirmed`, the name of the account that may have been created. - `connectionId` string, uuid: Present only on a partial failure. On `partial-failure-previous-connection-deletion`, the previous connection on the account (removed, or being removed). On `partial-failure-connection-creation`, the connection this request created or was creating: the id it was given before the create (the Feed Connection `id` if it was recorded). When the subtype is `connection-existence-not-confirmed`, the create's outcome is unknown and the connection may not exist in Xero. On `partial-failure-connection-deletion`, the connection being deleted (the item `id` also echoes it). Absent on `partial-failure-new-account-creation` and `partial-failure-new-account-existence-not-confirmed`. ## Other responses - `207`: Some items did not reach their desired state. Each item has its own result, so read the `items` array rather than the envelope. Partial failures are rare, and nearly all are recoverable by your app. On this endpoint a partial failure is `partial-failure-previous-connection-deletion` or `partial-failure-connection-creation`: resend the same item. `error.accountId` and `error.connectionId` identify the account and connection; `error.subtype` is optional diagnostics. If the resend returns 409 `feed-already-connected-in-current-organisation`, the earlier attempt was recorded: treat the item as created. A connection an earlier attempt left in Xero without a feed connection never causes that 409: the resend replaces it. See https://developer.xero.com/documentation/api/bankfeeds/feedconnections-2-0-errors/#partial-failures . `207` means the item codes were neither all 2xx nor all 4xx. A `PARTIAL_FAILURE` item has `statusCode` `500`: the item did not complete, and the state it left behind needs attention or could not be confirmed. `error.subtype` says which. A `REJECTED` item whose error is `internal-error` or `too-many-requests` also has `statusCode` `500`, so it makes the response a `207` (as does a batch in which all items are like that): something unexpected went wrong for that item, and nothing was written, or Xero confirmed that nothing took effect, so resend that item as it is. - `400`: All items are 4xx: either the request wrote nothing at all, or the request itself could not be processed. A `400` guarantees that none of the items was written and none reached its desired state. A batch in which any item was partly written has at least one `500` item code, so it is a `207`, never a `400`. When the request itself was at fault — an unreadable body, an empty `items` array, more than 50 items, or a missing header — the body is a problem object and there is no `items` array at all. - `401`: The request did not include a valid Xero Identity bearer token. A request missing both a token and a required header is answered `400`, because headers are checked first. - `403`: The Application, the Organisation, or the user is not permitted to make this request. Read `type` to distinguish the cases. - `415`: The request did not use `Content-Type: application/json`. V1 rewrote a wrong value for one legacy Application; V2 does not. - `500`: An error occurred inside Xero part-way through the request, and there is no `items` array to say how far it reached. Some items may already have been applied. Recover by re-sending the identical request. On a create, items already created come back as `feed-already-connected-in-current-organisation`; on a termination, items already terminated come back as `feed-not-found-or-already-deleted`. In both cases the remaining items are processed. ## Changes - **2026-10-27** (v2) `7b8338264030`: 1 info - endpoint added - **2026-10-01** (v2) `de9385475971`: 1 breaking - api path removed without deprecation [Operation history](https://skmtc.dev/xeroapi/apis/xero-bank-feeds-api/changes/FeedConnections/ExistingAccount/post.md) --- [API](https://skmtc.dev/xeroapi/apis/xero-bank-feeds-api.md) - [All operations](https://skmtc.dev/xeroapi/apis/xero-bank-feeds-api/llms.txt) - [OpenAPI document](https://skmtc.dev/xeroapi/apis/xero-bank-feeds-api/revisions/7b8338264030?raw)