Funds a box (AccountLink). Same id pattern as investments (groupId + source): pass source + accountId. Manual: omit accountId and pass name + currency (+ optional balance) to create and link in one step. Bank/crypto: accountId is the snapshot id from list_bank_connections / list_crypto_connections accounts[]. Optional creditAccountId for a bank card + payment pair. Optional alertSettings on any source. OAuth connect stays in-app.
POST
/v1/link_accountBody
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| idempotencyKey | string | Yes | — | Client-generated key (1–128 chars: letters, digits, . _ : -). Same key + same body replays; different body returns 409. Prefer Idempotency-Key HTTP header when calling the Tools API. |
| budgetId | string | Yes | — | Budget that owns the box. |
| boxId | string | Yes | — | Box to fund. |
| source | string | Yes | — | manual, bank, or crypto. |
| name | string | Conditional | — | Manual: display name for the new payment account (create+link). |
| currency | string | Conditional | — | Manual: ISO 4217 currency code for the new payment account. |
| balance | number | No | 0 | Manual: starting payment balance. |
| accountKind | string | No | checking | Manual: kind for the payment account. |
| accountId | string | Conditional | — | Account id for this source: existing manual id, or bank/crypto snapshot id from connections list. Omit on manual create+link (use name/currency). |
| paymentMode | string | No | account | Manual: account or creditCard. |
| creditName | string | No | — | Manual creditCard: credit account display name. |
| creditCurrency | string | No | — | Manual creditCard: credit account currency (defaults to currency). |
| creditBalance | number | Conditional | — | Manual creditCard: required starting credit balance. |
| creditCycleEndDay | number | No | — | Manual creditCard: cycle end day 1–31. |
| creditAccountId | string | No | — | Bank: credit-card snapshot id when pairing with accountId as payment. |
| alertSettings | object | No | — | Optional box account alerts — see alertSettings below. |
alertSettings
Optional object of box account alerts (same rules as in-app Accounts setup). Omit to leave alerts unset on link_account. On update_account, pass null to clear all alerts. Only rules with enabled: true are stored; disabled-only objects are dropped.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| balanceThreshold | object | No | — | Fire when the funding balance crosses a threshold. |
| balanceThreshold.enabled | boolean | No | false | Turn the threshold alert on. |
| balanceThreshold.amount | number | Conditional | — | Threshold amount in the account currency (required when enabled). |
| balanceThreshold.direction | string | No | below | below (balance drops under amount) or above (balance rises over amount). |
| insufficientForPlan | object | No | — | Fire when the funding balance cannot cover upcoming planned expenses in the box. |
| insufficientForPlan.enabled | boolean | No | false | Turn the insufficient-for-plan alert on. |
| creditExceedsPayment | object | No | — | Credit-card links only: fire when the card balance exceeds the linked payment account balance. |
| creditExceedsPayment.enabled | boolean | No | false | Turn the credit-exceeds-payment alert on. |
Response data
| Field | Type | Description |
|---|---|---|
| budgetId | string | Id of the budget this resource belongs to. |
| boxId | string | Id of the parent expense box. |
| source | string | manual, bank, or crypto. |
| accountLinkId | string | AccountLink id written on the box. |
| paymentMode | string | account or creditCard. |
| accountId | string | Payment account id (manual id or bank/crypto snapshot id). |
| creditAccountId | string | Credit account id when paymentMode is creditCard. |
| alertSettings | object | Persisted alert rules (null when none enabled). |