Banking

Bank accounts, bank connections through Stripe, statement uploads and staged bank transactions.

List bank accounts

GET /bank-accounts

Sends Vortex-Entity.

Requires banking:read.

Answers

  • 200 object. The entity's bank and card accounts.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Add a bank account

POST /bank-accounts

Sends Vortex-Entity and Idempotency-Key.

Adds a bank or card account fed by uploaded statements. It points at one ledger account: an asset for checking and savings, a liability for cards and loans. Requires banking:write.

Body

FieldTypeAbout
account_id requiredstring
name requiredstring

Up to 200 characters.

institutionstring

Up to 200 characters.

maskstring

Last four digits only.

kind requiredstring

One of: checking, savings, credit_card, loan, other.

Answers

  • 201 BankAccount. The bank account.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Start connecting a bank

POST /bank-accounts/feed-sessions

Sends Vortex-Entity and Idempotency-Key.

Starts a Stripe Financial Connections session. Open it in the owner's browser with Stripe.js using client_secret. The bank login happens on Stripe's page and SYNC never sees it. Answers 503 bank_feeds_off until Stripe keys are set. Requires banking:write and accounts:write.

Answers

  • 201 object. The session.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

List the accounts chosen in a session

GET /bank-accounts/feed-sessions/{session_id}

Sends Vortex-Entity.

Requires banking:write and accounts:write.

Parameters

NameInTypeAbout
session_id requiredpathstring

Answers

  • 200 object. The accounts.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Connect one chosen account

POST /bank-accounts/feed-links

Sends Vortex-Entity and Idempotency-Key.

Attaches the account to an existing bank account (bank_account_id) or makes a new one on a ledger account (account_id), checks its owner against the business's legal name, and starts daily transactions. A name that doesn't match is a warning, not a block. Lines dated before start_on, the opening balances or the last reconciliation don't come in. Requires banking:write and accounts:write.

Body

FieldTypeAbout
stripe_account_id requiredstring
bank_account_idstring (uuid)
account_idstring (uuid)
start_on requiredstring (date)

Answers

  • 201 BankAccount. The connected bank account.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Disconnect a bank connection

POST /bank-accounts/{bank_account_id}/feed/disconnect

Sends Vortex-Entity and Idempotency-Key.

Stops the feed at Stripe. Lines already here stay. Requires banking:write and accounts:write.

Parameters

NameInTypeAbout
bank_account_id requiredpathstring

Answers

  • 200 BankAccount. The bank account.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Confirm an account belongs to this business

POST /bank-accounts/{bank_account_id}/feed/confirm-owner

Sends Vortex-Entity and Idempotency-Key.

For an owner name that didn't match or wasn't shared. Recorded in the audit log. Requires banking:write and accounts:write.

Parameters

NameInTypeAbout
bank_account_id requiredpathstring

Answers

  • 200 BankAccount. The bank account.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

List statements

GET /bank-accounts/{bank_account_id}/statements

Sends Vortex-Entity.

A bank account's uploaded statements, newest first, up to 100. Requires banking:read.

Parameters

NameInTypeAbout
bank_account_id requiredpathstring

Answers

  • 200 object. The statements.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Upload a statement

POST /bank-accounts/{bank_account_id}/statements

Sends Vortex-Entity and Idempotency-Key.

Uploads a bank or card statement as CSV or OFX, up to 4 MB. PDF and image statements answer 422 for now. SYNC reads every line and, when the opening and closing balances are known, checks that opening plus deposits minus withdrawals equals closing. A file that doesn't add up stages nothing. Requires banking:write.

Parameters

NameInTypeAbout
bank_account_id requiredpathstring

Body

FieldTypeAbout
file requiredstring
opening_balanceAmount

From the statement, if the file doesn't carry it.

closing_balanceAmount

From the statement, if the file doesn't carry it.

Answers

  • 202 Statement. The statement, being processed.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Undo a reviewed bank transaction

POST /bank-transactions/{bank_transaction_id}/undo

Sends Vortex-Entity and Idempotency-Key.

Puts a matched, posted or excluded line back in the review queue. A posted line's entry is reversed, never erased. Lines inside a reconciled range can't be undone. Requires banking:write.

Parameters

NameInTypeAbout
bank_transaction_id requiredpathstring

Answers

  • 200 BankTransaction. The bank transaction, back in review.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Get a statement

GET /statements/{statement_id}

Sends Vortex-Entity.

Parameters

NameInTypeAbout
statement_id requiredpathstring

Answers

  • 200 Statement. The statement and its footing check.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

List staged bank transactions

GET /bank-transactions

Sends Vortex-Entity.

Requires banking:read.

Parameters

NameInTypeAbout
limitqueryinteger
starting_afterquerystring
start_datequerystring (date)
end_datequerystring (date)
bank_account_idquerystring
statusqueryBankTransactionStatus

Answers

  • 200 any. A page of bank transactions.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Approve a bank transaction

POST /bank-transactions/{bank_transaction_id}/approve

Sends Vortex-Entity and Idempotency-Key.

Posts the staged line, using SYNC's suggestion unless the body overrides it, or matches it to an existing journal entry. Set save_as_rule to post similar lines automatically from now on. Requires banking:write.

Parameters

NameInTypeAbout
bank_transaction_id requiredpathstring

Body

BankTransactionApproval

Answers

  • 200 BankTransaction. The posted bank transaction.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Exclude a bank transaction

POST /bank-transactions/{bank_transaction_id}/exclude

Sends Vortex-Entity and Idempotency-Key.

Marks a staged line as a duplicate or personal item so it never posts. Nothing is deleted. Requires banking:write.

Parameters

NameInTypeAbout
bank_transaction_id requiredpathstring

Body

FieldTypeAbout
reason requiredstring

One of: duplicate, personal, not_business, other.

notestring

Up to 500 characters.

Answers

  • 200 BankTransaction. The excluded bank transaction.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what