{"openapi":"3.0.3","info":{"title":"Astrada Banking API","version":"2024-02-28","contact":{"email":"developer@astrada.co"},"description":"The Banking API connects bank accounts (via Plaid), syncs bank transactions, and reconciles them against card transactions. Import this definition into Postman to get a ready-to-run collection. See the \"Banking API in Postman\" guide for auth and base URLs.\n"},"servers":[{"url":"https://api.sandbox.astrada.co","description":"Sandbox"}],"tags":[{"name":"bank-links","description":"Manage bank enrollment links. A bank link represents an invitation for a user to connect their bank account via Plaid."},{"name":"bank-accounts","description":"Manage connected bank accounts. Bank accounts are created automatically when a bank link enrollment is completed."},{"name":"bank-subscriptions","description":"Manage bank subscriptions (Plaid connections). A subscription represents an active connection to a financial institution."},{"name":"bank-transactions","description":"Access bank transactions synced from connected accounts. Transactions are ingested via Plaid and can be matched against card transactions."},{"name":"transaction-matches","description":"Access transaction matches between bank and card transactions, including confidence scores and match reasoning."}],"externalDocs":{"description":"Find out more about Astrada API.","url":"https://docs.astrada.co/reference"},"paths":{"/bank-links":{"get":{"tags":["bank-links"],"summary":"List bank links","description":"Returns a list of bank links under the account.\n\nBy default, `GET /bank-links` returns bank links ordered by the latest `createdAt`.\n\nThis endpoint supports cursor-based pagination.\n","operationId":"ListBankLinks","parameters":[{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/bank-link-state"},{"$ref":"#/components/parameters/banking-limit"},{"$ref":"#/components/parameters/cursor"}],"security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/bank-link"}},"pagination":{"type":"object","required":["hasMore"],"properties":{"cursor":{"type":"string","description":"Cursor to use for the next page of results."},"hasMore":{"type":"boolean","description":"Whether there are more results available."}}}}},"examples":{"Example List Bank Links Response":{"value":{"items":[{"_links":{"self":{"href":"/bank-links/enrollment_792dcb7d"},"bankAccounts":[{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"}]},"id":"enrollment_792dcb7d","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","state":"completed","provider":"plaid","hostedLink":null,"linkExpiresAt":null,"completedAt":"2025-10-03T10:55:42.000Z","bankAccounts":[{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","name":"Checking"}],"createdAt":"2025-10-03T10:25:27.069Z"},{"_links":{"self":{"href":"/bank-links/enrollment_a1b2c3d4"}},"id":"enrollment_a1b2c3d4","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","state":"pending","provider":"plaid","hostedLink":"https://hosted.plaid.com/link/abc123","linkExpiresAt":"2025-10-04T14:25:27.000Z","createdAt":"2025-10-04T10:25:27.069Z"}],"pagination":{"cursor":"ZXhhbXBsZQ==","hasMore":false}}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}},"post":{"tags":["bank-links"],"summary":"Create bank link","description":"Creates a new bank link to initiate a bank enrollment. The response includes a `hostedLink` URL where the user can connect their bank account via Plaid.\n\nThe hosted link expires after 4 hours. If the link expires before the user completes enrollment, retrieve the bank link via `GET /bank-links/{bankLinkId}` to get a refreshed URL.\n\nCreating a bank link with an ID that already exists for the account will return a `409 Conflict` error, unless the existing link has expired.\n\nA refused create returns a JSON body with `statusCode` and `message`. These errors also carry a `code`, a stable name to branch on so that you never match on `message` text (the `409` above has no `code`):\n\n- `404` `SUBACCOUNT_NOT_FOUND`: `subaccountId` is not one of the account's subaccounts. Nothing is created. The message is `Subaccount not found for this account`.\n- `403` `BANK_ENROLLMENT_DISABLED`: a create is refused when the account has locked bank enrollment (`enrollmentPolicy.bankEnrollmentLocked` is `true` on the subaccount) and the subaccount's `enrollmentPolicy.bankEnrollment` value does not allow a bank link for this card. Otherwise the check does not refuse. Nothing is created. The message is `Bank linking is not enabled for this card on this account`. The body also has a `reason`: `bank-enrollment-off` when the setting is `off`, `network-not-allowed` when it does not allow the card's network, and `network-unknown` when it limits the networks and the request does not show the card's network. The card's network comes from the request: American Express when the link uses the `amex_only` customization, otherwise `bin6` (a first digit of `4` is Visa, `2` or `5` is Mastercard, and any other digit, a `3` included, is unknown). Without `bin6` it is unknown.\n- `403` `MASTERCARD_CLIENT_NOT_PROVISIONED` and `PLAID_EC_NOT_PROVISIONED`: the account is not set up for bank linking on that provider yet. The messages are `This account is not set up for Mastercard bank linking yet` and `This account is not set up for Plaid bank linking yet`.\n- `403` `PLAID_CUSTOMIZATION_NOT_PROVISIONED`: Plaid refused the Link customization this link asked for, because the account's Plaid client cannot use it, and no fallback applied. Nothing is created. The message is `This account is not fully set up for Plaid bank linking yet`. A customization other than `amex_only` (one set by the bank-linking policy's `plaidLinkCustomizationName`) answers this at once. When Plaid refuses `amex_only`, from `filters.linkCustomizationName` or from the policy, the create is retried once with the environment's pinned customization in its place, or with no customization when the environment pins none. If Plaid accepts the retry, the link is created as usual: its hosted session opens without the `amex_only` customization, and its completion is still held to American Express institutions. For `amex_only`, only a refused retry answers this error. Astrada fixes it in the account's Plaid setup, so sending the same request again does not help.\n- `400` `INVALID_LINK_FILTERS`: `filters` asks for more than the account's bank-linking policy allows, or for a customization that is not allowed.\n- `400` `PROVIDER_NOT_ENABLED_FOR_ACCOUNT`: `provider` is not enabled for the account.\n- `400` `PROVIDER_NOT_SUPPORTED_FOR_COUNTRY`: no provider supports `countryCode` for the chosen `provider`.\n","operationId":"CreateBankLink","security":[{"main-auth":["banking:write"]}],"requestBody":{"description":"Bank link creation request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"description":"A client-provided identifier for the bank link. Must be alphanumeric with hyphens and underscores only.","type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$"},"subaccountId":{"description":"The subaccount identifier to associate with this bank link. A subaccount that does not belong to the account is rejected with `404` (`SUBACCOUNT_NOT_FOUND`).","type":"string","format":"uuid"},"filters":{"type":"object","description":"Optional per-link narrowing of the account's bank-linking policy. Values may only NARROW what the policy allows — the current system default is `accountTypes: [credit]` (credit-card accounts only). Requests widening beyond the policy are rejected with `400`. Account-type enforcement is applied by the provider at link-token creation and also filters the institution-select list.\n","properties":{"accountTypes":{"type":"array","minItems":1,"description":"Account types selectable during this hosted session.","items":{"type":"string","enum":["checking","savings","credit"]}},"linkCustomizationName":{"type":"string","minLength":1,"maxLength":100,"description":"Name of an allowlisted provider (Plaid) Link customization to apply to this hosted session — e.g. `amex_only` to surface an Amex-first institution list with a tailored headline for card-enrollment connections. Only `amex_only` is accepted; any other name is rejected with `400` (`INVALID_LINK_FILTERS`). A requested customization takes the place of the bank-linking policy's. Institution steering is by account-type filtering plus the customization's Dashboard configuration — the provider does not support hard institution pre-selection for hosted sessions.\n"}}},"bin6":{"type":"string","pattern":"^\\d{6}$","description":"First 6 digits captured client-side before an institution pivot (e.g. an American Express BIN typed into the card form before the SDK pivots to bank linking). Persisted with the link. Attached as the completion-time bank-derived card's `first6digits` when the completion has exactly one eligible candidate account.\n"},"provider":{"type":"string","enum":["plaid","mastercard"],"description":"Open-banking provider to create the link on. Omitted, the subaccount's configured default applies (system default: `plaid`). A provider outside the subaccount's configured allowlist, or one not enabled on the platform, is rejected with `400`. The provider is fixed at creation — every later operation on the link uses the value it was created with.\n"},"countryCode":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 3166-1 alpha-3 country of the institution to connect (e.g. `USA`, `DEU`). Omitted, the subaccount's configured default applies (system default: `USA`). Combined with `provider` to select the concrete integration; a country the selected provider does not support is rejected with `400`.\n"},"language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8}){0,3}$","description":"Language of the hosted bank-linking screens, as a BCP 47 tag such as `en`, `en-US` or `sv-SE`. A tag that matches the pattern is accepted; any other value is rejected with `400`. For a Plaid link, the language part of the tag (`sv` for `sv-SE`) is used when Plaid supports it, Astrada has turned that language on, and no Link customization applies to the link. Otherwise the screens are in English and the request still succeeds. Plaid Link supports `da`, `nl`, `en`, `et`, `fr`, `de`, `hi`, `it`, `lv`, `lt`, `no`, `pl`, `pt`, `ro`, `es`, `sv` and `vi`. Plaid's Norwegian is `no`, so `nb` and `nb-NO` fall back to English. Other providers ignore this field. The language is kept with the link, so a refreshed hosted link uses it again.\n"},"persona":{"type":"string","enum":["admin","cardholder"],"description":"Who the bank login belongs to. `cardholder`: a page for one person, such as an employee, who links their own bank login. `admin`: the company. Omitted, the link is a company link, as with `admin`, which is how every link behaved before this field existed.\n\nThe link's owner decides which cards its accounts can join: two bank accounts can count as the same card only when their links have the same owner. Cardholder links sent with the same `cardholderKey` share an owner, a cardholder link without a key is its own owner, and every company link has the company as its owner, so a cardholder link never joins a company link's card.\n"},"cardholderKey":{"type":"string","minLength":1,"maxLength":256,"description":"Your stable id for the person on the page, used only with `persona: cardholder`, so that all of their links share one owner. Optional: without it, each cardholder link is its own owner. A key sent with `persona: admin`, or with no `persona`, is ignored. Surrounding whitespace is trimmed, and 1 to 256 characters must remain. Astrada stores only a keyed hash of the key, never the key itself.\n\nThe key must be one that no other user can guess: an opaque value your backend issues for that person and gives only to their page, such as a random id, or an HMAC of their employee id made with your own secret. Never send an email address, an employee number or anything else another user could guess. A guessed key can join another person's card.\n"},"consent":{"$ref":"#/components/schemas/bank-link-consent"}},"required":["id","subaccountId"]},"examples":{"BankLinkRequestExample":{"value":{"id":"enrollment_abc123","subaccountId":"50cced63-ee4e-4ff7-a469-aaa989f220f2"}},"AmexCardEnrollmentExample":{"value":{"id":"enrollment_amex_7f2c","subaccountId":"50cced63-ee4e-4ff7-a469-aaa989f220f2","filters":{"accountTypes":["credit"],"linkCustomizationName":"amex_only"},"bin6":"371449"}},"CardholderBankLinkExample":{"value":{"id":"enrollment_cardholder_4e1a","subaccountId":"50cced63-ee4e-4ff7-a469-aaa989f220f2","persona":"cardholder","cardholderKey":"ch_7f3c9a2e5b814d06a1c8e2f4b9d7a3c5","filters":{"accountTypes":["credit"],"linkCustomizationName":"amex_only"},"bin6":"371449"}}}}}},"responses":{"201":{"description":"Bank link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-link"},"examples":{"Example Create Bank Link Response":{"value":{"_links":{"self":{"href":"/bank-links/enrollment_abc123"}},"id":"enrollment_abc123","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"50cced63-ee4e-4ff7-a469-aaa989f220f2","state":"pending","provider":"plaid","hostedLink":"https://hosted.plaid.com/link/abc123","linkExpiresAt":"2025-10-03T14:25:27.000Z","createdAt":"2025-10-03T10:25:27.069Z"}}}}},"links":{"GetBankLink":{"operationId":"GetBankLink","parameters":{"bankLinkId":"$response.body#/id"},"description":"Retrieve the created bank link."},"CompleteBankLink":{"operationId":"PatchBankLink","parameters":{"bankLinkId":"$response.body#/id"},"description":"Complete the bank link enrollment."}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-links/{bankLinkId}":{"parameters":[{"$ref":"#/components/parameters/bank-link-id"}],"get":{"tags":["bank-links"],"summary":"Retrieve bank link","description":"Returns detailed information about a specific bank link by its identifier.\n\nIf the bank link is in `pending` state and the hosted link URL has expired, this endpoint will automatically refresh the URL and return the updated link.\n\nOnce the user has finished the hosted flow, a read of the link answers `completed`: the link completes without a `PATCH` from you.\n","operationId":"GetBankLink","security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-link"},"examples":{"Example Get Bank Link Response":{"$ref":"#/components/examples/bank-link"}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}},"patch":{"tags":["bank-links"],"summary":"Complete bank link","description":"Completes a bank link enrollment, transitioning it from `pending` to `completed` state. The request body must contain `state: \"completed\"`.\n\nWhen a bank link is completed, the system exchanges the enrollment credentials with the provider, creates a bank subscription (connection), and discovers the associated bank accounts.\n\nA link that is no longer `pending` answers `409`; read it with `GET /bank-links/{bankLinkId}`.\n\nThe PATCH response echoes the bank link record only. The discovered `bankAccounts` (with each account's `cardIds` and any minted `cards`) are returned by `GET /bank-links/{bankLinkId}`, not by this PATCH.\n","operationId":"PatchBankLink","security":[{"main-auth":["banking:write"]}],"requestBody":{"description":"Bank link completion request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"description":"The target state for the bank link. Only `completed` is accepted.","type":"string","enum":["completed"]},"consent":{"$ref":"#/components/schemas/bank-link-consent"}},"required":["state"]},"examples":{"BankLinkRequestExample":{"value":{"state":"completed"}}}}}},"responses":{"200":{"description":"Bank link completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-link"},"examples":{"Example Complete Bank Link Response":{"$ref":"#/components/examples/bank-link"}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}},"delete":{"tags":["bank-links"],"summary":"Delete bank link","description":"Deletes a bank link and all associated resources, including the bank subscription, bank accounts, and bank transactions.\n\nCards are not deleted. A `bank-feed` subscription created at completion is deactivated; a card enrolled by its number only loses its bank account. Each still-active account sends `bankaccount.state_changed`, and each changed subscription sends `cardsubscription.updated`.\n\n**Note:** This action is irreversible and will revoke access to the connected financial institution.\n","operationId":"DeleteBankLink","security":[{"main-auth":["banking:admin"]}],"responses":{"204":{"description":"Bank link deleted"},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-links/{bankLinkId}/sync":{"parameters":[{"$ref":"#/components/parameters/bank-link-id"}],"post":{"tags":["bank-links"],"summary":"Sync bank link","description":"Triggers a manual sync of transactions for the bank link's associated subscription. This fetches the latest transactions from the financial institution.\n\nTransaction syncs also occur automatically via provider webhooks and scheduled jobs. Use this endpoint to force an immediate sync when needed.\n","operationId":"SyncBankLink","security":[{"main-auth":["banking:admin"]}],"requestBody":{"description":"Optional sync configuration","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"description":"The types of webhook events to emit after syncing.","type":"array","items":{"type":"string","enum":["banktransaction.created","transaction.match.created"]}},"force":{"description":"Set to `true` to force a full sync even if no new transactions are detected.","type":"boolean","default":false}}},"examples":{"SyncWithWebhooksExample":{"value":{"webhooks":["banktransaction.created"],"force":false}}}}}},"responses":{"200":{"description":"Sync triggered","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation message."}}},"examples":{"Example Sync Response":{"value":{"message":"Transactions synced successfully"}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts":{"get":{"tags":["bank-accounts"],"summary":"List bank accounts","description":"Returns a list of bank accounts under the account. Bank accounts are created automatically when a bank link enrollment is completed.\n\nBy default, `GET /bank-accounts` returns bank accounts ordered by the latest `createdAt`.\n\nThis endpoint supports cursor-based pagination.\n","operationId":"ListBankAccounts","parameters":[{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/bank-account-state"},{"$ref":"#/components/parameters/card-id-2"},{"$ref":"#/components/parameters/banking-limit"},{"$ref":"#/components/parameters/cursor"}],"security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/bank-account"}},"pagination":{"type":"object","required":["hasMore"],"properties":{"cursor":{"type":"string","description":"Cursor to use for the next page of results."},"hasMore":{"type":"boolean","description":"Whether there are more results available."}}}}},"examples":{"Example List Bank Accounts Response":{"value":{"items":[{"_links":{"self":{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"transactions":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11?bankAccountId=3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"bankLink":{"href":"/bank-links/enrollment_792dcb7d"}},"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankLinkId":"enrollment_792dcb7d","externalId":"plaid_acc_792dcb7d","cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"],"cards":[],"institutionName":"Chase","name":"Checking","mask":"1234","type":"checking","currency":"USD","state":"active","subscriptionState":"active","lastSyncedAt":"2025-10-03T11:12:07.000Z","createdAt":"2025-10-03T10:55:42.000Z","updatedAt":"2025-10-03T10:55:42.000Z"},{"_links":{"self":{"href":"/bank-accounts/9b7e4d2f-8a3c-1e6f-d5b0-2c4a6e8f0d1b"},"transactions":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11?bankAccountId=9b7e4d2f-8a3c-1e6f-d5b0-2c4a6e8f0d1b"},"bankLink":{"href":"/bank-links/enrollment_792dcb7d"}},"id":"9b7e4d2f-8a3c-1e6f-d5b0-2c4a6e8f0d1b","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankLinkId":"enrollment_792dcb7d","externalId":"plaid_acc_792dcb7e","cardIds":[],"cards":[],"institutionName":"Chase","name":"Savings","mask":"5678","type":"checking","currency":"USD","state":"active","subscriptionState":"active","lastSyncedAt":"2025-10-03T11:12:07.000Z","createdAt":"2025-10-03T10:55:42.000Z","updatedAt":"2025-10-03T10:55:42.000Z"}],"pagination":{"hasMore":false}}}}}},"links":{"GetFirstBankAccount":{"operationId":"GetBankAccount","parameters":{"bankAccountId":"$response.body#/items/0/id"},"description":"Retrieve the first bank account from the list."}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/link-enrolled-cards":{"post":{"tags":["bank-accounts"],"summary":"Link enrolled cards to bank accounts (admin backfill)","description":"Admin backfill/retry for immediate mask-linking: matches the subaccount's ENROLLED cards against its credit bank accounts by mask (an enrolled card's last 4 digits) and links each exact match. The same exactly-one-or-skip rules as completion-time linking apply: a mask matching multiple cards, or multiple accounts claiming a mask, links nothing (the scheduled mask sweep retries this every few hours). Idempotent: already-linked pairs are skipped. Intended for onboarding backfills (cards enrolled before the bank link) and recovery after a transient directory failure at completion. Emits no webhook; linked cardIds appear on subsequent bank-account reads.\n\nThe body takes `subaccountId` only; any other field is a `400`. The admin actions (minting cards for cardless accounts, the cardholder backfill) are on `POST /bank-accounts/maintenance` at `banking:admin`.\n","operationId":"LinkEnrolledCards","security":[{"main-auth":["banking:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["subaccountId"],"properties":{"subaccountId":{"type":"string","format":"uuid","description":"The subaccount whose enrolled cards and bank accounts to match."}}},"example":{"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"}}}},"responses":{"201":{"description":"Backfill executed. Maps each bank account that gained links to the card ids linked in this run (empty object when nothing matched).","content":{"application/json":{"schema":{"type":"object","required":["linked"],"properties":{"linked":{"type":"object","description":"bankAccountId -> cardIds linked in THIS run.","additionalProperties":{"type":"array","items":{"type":"string","format":"uuid"}}}}},"examples":{"Example Backfill Response":{"value":{"linked":{"059d5e6a-cfb1-46e6-ab84-6586582b6b58":["da28e1b8-c7a4-4575-b72f-3a88d6fe34df"]}}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/maintenance":{"post":{"tags":["bank-accounts"],"summary":"Bank account maintenance for a subaccount (admin)","description":"Admin maintenance over one subaccount. It first runs the same mask pass as `POST /bank-accounts/link-enrolled-cards`, then each action the request asks for. The actions create cards on the cards platform or rewrite stored rows, so this route needs `banking:admin`, while the mask pass alone stays on `link-enrolled-cards` at `banking:write`. The caller's account comes from its token: it can run maintenance on any subaccount of its own account, and a subaccount of another account simply matches nothing (an empty result, not a `403`).\n\nThree optional actions, each off by default:\n\n- `mint: true` runs the completion-time mint pass over the subaccount's credit bank accounts that a completed link left without a card (the same-last-4 American Express case), so each gains a bank-feed card. Idempotent: an account that already holds a minted card is skipped.\n- `backfillJunctionLast4: true` fills, for the subaccount's card links, the last 4 each link answers to where it is still unknown, from the cards directory. Idempotent.\n- `createCardholderCards: true` runs, now and for this subaccount only, what a scheduled job does every 30 minutes: it gives each cardholder behind a pooled American Express billing account (a supplementary card that is not its own Plaid account) a bank-feed card of their own, with the cardholder's name, so their transactions can be emitted on that card. It does nothing unless Astrada has switched the feature on for the subaccount; the switches are set by Astrada only, from inside the platform, and no request can set them. Idempotent: a cardholder who already has a card is never given another.\n\nThe actions run in the order above, after the mask pass. If the cards directory cannot be read, the mask pass links nothing and still returns `201`; each action then reads the directory again on its own and says so in its result (`directoryUnavailable`), or, for `mint` with accounts to screen, fails rather than mint unscreened. Any step that fails returns `400` and runs nothing after it (steps before it have done their work, and every step is idempotent, so the request can simply be repeated). Emits no webhook from banking; a card created here produces the cards platform's usual card-subscription events.\n","operationId":"BankAccountMaintenance","security":[{"main-auth":["banking:admin"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["subaccountId"],"properties":{"subaccountId":{"type":"string","format":"uuid","description":"The subaccount to run maintenance over."},"mint":{"type":"boolean","default":false,"description":"After the mask pass, also mint a bank-feed card for each of the subaccount's eligible credit bank accounts that holds no card. Accounts that already hold a minted card are skipped.\n"},"backfillJunctionLast4":{"type":"boolean","default":false,"description":"After the mask pass, also fill each of the subaccount's card links with the last 4 it answers to, where still unknown, from the cards directory.\n"},"createCardholderCards":{"type":"boolean","default":false,"description":"After the mask pass, also create and name the bank-feed cards of the cardholders behind the subaccount's pooled American Express billing accounts, as the scheduled job does. Does nothing unless Astrada has switched the feature on for the subaccount.\n"}}},"examples":{"Mask pass only":{"value":{"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"}},"Mask pass, then mint and cardholder cards":{"value":{"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","mint":true,"createCardholderCards":true}}}}}},"responses":{"201":{"description":"Maintenance executed. Maps each bank account that gained links to the card ids linked in this run (empty object when nothing matched). The other fields appear only for the actions the request asked for.","content":{"application/json":{"schema":{"type":"object","required":["linked"],"properties":{"linked":{"type":"object","description":"bankAccountId -> cardIds linked in THIS run.","additionalProperties":{"type":"array","items":{"type":"string","format":"uuid"}}},"minted":{"type":"object","description":"Present whenever `mint: true` was sent (`{}` when nothing was minted). bankAccountId -> the card minted for it in THIS run. `linkedHere` is false when the card is held by a sibling account instead (a re-link of the same bank; the background re-home converges it).\n","additionalProperties":{"type":"object","required":["cardId","subscriptionId","linkedHere"],"properties":{"cardId":{"type":"string","format":"uuid"},"subscriptionId":{"type":"string","format":"uuid"},"linkedHere":{"type":"boolean"}}}},"skipped":{"type":"object","description":"Present whenever `mint: true` was sent (`{}` when nothing was skipped). bankAccountId -> why the mint pass did not mint for it: `already_materialized` (the account already holds a minted card), `existing_enrolled_card` (its last 4 belongs to a card the customer enrolled directly) or `no_institution_id` (the connection never recorded its institution).\n","additionalProperties":{"type":"string"}},"failures":{"type":"object","description":"Present whenever `mint: true` was sent (`{}` when no mint failed). bankAccountId -> the failure. The pass is idempotent, so the request can simply be repeated.\n","additionalProperties":{"type":"string"}},"junctionLast4":{"type":"object","description":"Present only when `backfillJunctionLast4: true` was sent.","required":["rowsUpdated","rowsUnresolved","directoryUnavailable"],"properties":{"rowsUpdated":{"type":"integer","description":"Links that gained a last 4 in this run."},"rowsUnresolved":{"type":"integer","description":"Links still without one (the directory did not list the card)."},"directoryUnavailable":{"type":"boolean","description":"True when this action's own read of the cards directory failed (the mask pass does not fail on it); call again later."}}},"cardholderCards":{"type":"object","description":"Present only when `createCardholderCards: true` was sent. Counts only; no cardholder name is ever returned.\n","required":["enabled","routeEnabled","accounts","suffixesSeen","created","linkedEnrolled","named","relinked","failed","skipped","directoryUnavailable"],"properties":{"enabled":{"type":"boolean","description":"False when card creation is not switched on for the subaccount; nothing was created."},"routeEnabled":{"type":"boolean","description":"True when each cardholder's transactions are emitted on their own card."},"accounts":{"type":"integer","description":"Pooled American Express billing accounts served."},"suffixesSeen":{"type":"integer","description":"Distinct cardholders (by the card's last 4) seen in those accounts' transactions."},"created":{"type":"integer","description":"Cardholder cards created in this run."},"linkedEnrolled":{"type":"integer","description":"Cards the cardholder had already enrolled, linked instead of creating one."},"named":{"type":"integer","description":"Cards whose cardholder name was written in this run."},"relinked":{"type":"integer","description":"Cardholder cards found on another bank account of the subaccount after a re-link, left where they are and counted (the background re-home moves them)."},"failed":{"type":"integer","description":"Cards that could not be created this run; the next run tries again."},"skipped":{"type":"object","description":"Reason -> count of cardholders given no card of their own (their transactions stay on the account's main card). Reasons: `no_primary`, `ambiguous_primary`, `bulk_owned`, `ambiguous_enrolled`, and the permanent `deactivated`, `not_active`, `unlinked` and `foreign_reuse`. Only reasons with a count appear.\n","additionalProperties":{"type":"integer"}},"directoryUnavailable":{"type":"boolean","description":"True when this action's own read of the cards directory failed; no card was created this run."}}}}},"examples":{"Mask pass only":{"value":{"linked":{"059d5e6a-cfb1-46e6-ab84-6586582b6b58":["da28e1b8-c7a4-4575-b72f-3a88d6fe34df"]}}},"With mint and cardholder cards":{"value":{"linked":{},"minted":{"3a1f0c2e-9b4d-4e7a-8c6f-1d2e3f4a5b6c":{"cardId":"7c9e6679-7425-40de-944b-e07fc1f90ae7","subscriptionId":"2f1a4b3c-5d6e-4f70-8a9b-0c1d2e3f4a5b","linkedHere":true}},"skipped":{"8b2d4f6a-1c3e-4a5b-9d7f-2e4a6c8b0d1f":"already_materialized"},"cardholderCards":{"enabled":true,"routeEnabled":false,"accounts":1,"suffixesSeen":3,"created":2,"linkedEnrolled":0,"named":3,"relinked":0,"failed":0,"skipped":{},"directoryUnavailable":false}}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/{bankAccountId}":{"parameters":[{"$ref":"#/components/parameters/bank-account-id"}],"get":{"tags":["bank-accounts"],"summary":"Retrieve bank account","description":"Returns detailed information about a specific bank account by its identifier.","operationId":"GetBankAccount","security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-account"},"examples":{"Example Get Bank Account Response":{"$ref":"#/components/examples/bank-account"}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}},"patch":{"tags":["bank-accounts"],"summary":"Update bank account","description":"Updates a bank account. Card links are detected automatically: a scheduled sweep re-checks each cardless credit account every few hours and links an enrolled card whose last 4 digits match the account's mask, without any API call. This endpoint is the manual override: use it to pre-link a card immediately, correct an assignment, or import history.\n\nEach card in `cardIds` must belong to the same subaccount as the bank account. A card can only be linked to one bank account at a time — attempting to link a card that is already associated with another bank account will return a `409 Conflict` error.\n\nA card that cannot take a bank-account link is also rejected with `409 Conflict` (`CARD_NOT_LINKABLE`) before any change is applied: one whose only enrollment is a bulk feed, or whose subscriptions are all in a dead, non-attachable state. If the cards directory cannot be consulted, this screen is skipped (fail-open) rather than blocking the update.\n\n`cardIds` is a full replacement. Send `cardIds: []` to clear explicit links (the scheduled mask sweep can re-link a matching card on its next run).\n\nCards Astrada created for the individual cardholders of a pooled American Express billing account are managed by the platform: a `cardIds` list without them does not remove them (they leave when the card is deactivated or the account is disconnected or deleted). An enrolled card that was linked for one such cardholder can be removed here, and stays removed: it is not linked again automatically.\n\nOptionally include a `backfill` object with `startDate` and/or `endDate` to trigger a backfill of historical bank transactions for the specified date range. An automatically detected link re-matches the account's already-synced unmatched transactions around the new card's activity on its own; IMPORTING bank history from before the link (pulling older transactions from the provider) still happens only through this endpoint's `backfill`.\n\nThe current card set is always readable at `GET /bank-accounts/{bankAccountId}` (`cardIds`), and `GET /bank-accounts?cardId=` finds the account a card is linked to.\n","operationId":"UpdateBankAccount","security":[{"main-auth":["banking:write"]}],"requestBody":{"description":"Bank account update request","required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Link or replace linked cards","type":"object","required":["cardIds"],"properties":{"cardIds":{"description":"The identifiers of cards to link to this bank account for transaction matching. Send an empty array to unlink all cards. Each card must belong to the same subaccount.","type":"array","items":{"type":"string","format":"uuid"}},"backfill":{"description":"Optional backfill configuration to import historical bank transactions for the linked card.","type":"object","properties":{"startDate":{"description":"Start date for the backfill range in YYYY-MM-DD format.","type":"string","format":"date"},"endDate":{"description":"End date for the backfill range in YYYY-MM-DD format.","type":"string","format":"date"}}}}},{"title":"Disconnect the account","type":"object","required":["state"],"properties":{"state":{"description":"Set to `disconnected` to stop this account's feed while retaining its transaction history. This is a soft, reversible disconnect (re-linking the institution restores it) and does not delete data. Use `DELETE /bank-accounts/{bankAccountId}` to remove the account and its transactions.","type":"string","enum":["disconnected"]},"reason":{"description":"Optional free-text reason recorded with the disconnect.","type":"string"},"cardId":{"description":"Optional SCOPE for the disconnect. Omit for the historical account-scoped behaviour: the whole account is torn down and every card on it loses the feed. Supply the card that was deactivated to scope it to that card — its link is removed and the account keeps feeding any other cards attached to it. Disconnecting the last remaining card still tears the account down, so a single-card account behaves identically either way.\n","type":"string","format":"uuid"}}}]},"examples":{"LinkCardExample":{"value":{"cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"]}},"LinkMultipleCardsExample":{"value":{"cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3","8abc3d12-1bb6-4912-b421-6e8f2a7c9d0e"]}},"LinkCardWithBackfillExample":{"value":{"cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"],"backfill":{"startDate":"2025-09-01","endDate":"2025-10-01"}}},"UnlinkAllCardsExample":{"value":{"cardIds":[]}},"DisconnectAccountExample":{"value":{"state":"disconnected","reason":"customer_requested"}},"DisconnectOneCardExample":{"value":{"state":"disconnected","reason":"subscription_deactivated","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3"}}}}}},"responses":{"200":{"description":"Bank account updated","content":{"application/json":{"schema":{"type":"object","required":["id","cardIds","state","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The bank account identifier."},"cardIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The linked card identifiers."},"state":{"type":"string","description":"The current state of the bank account."},"updatedAt":{"type":"string","format":"date-time","description":"When the bank account was last updated."},"backfill":{"type":"object","description":"Backfill results returned when a backfill was requested.","properties":{"transactionsProcessed":{"type":"integer","description":"Number of historical transactions processed."},"matchesFound":{"type":"integer","description":"Number of matches found during backfill."}}}}},"examples":{"Example Update Bank Account Response":{"value":{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"],"state":"active","updatedAt":"2025-10-03T11:00:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}},"delete":{"tags":["bank-accounts"],"summary":"Delete bank account","description":"Deletes a bank account and all associated bank transactions, transaction matches, and card links.\n\nCards are not deleted. A `bank-feed` subscription created from this account is deactivated; a card enrolled by its number only loses its bank account. The account sends `bankaccount.state_changed` with reason `deleted`.\n\n**Note:** This action is irreversible. Deleting the last account of a bank connection also removes the connection at the bank.\n","operationId":"DeleteBankAccount","security":[{"main-auth":["banking:admin"]}],"responses":{"204":{"description":"Bank account deleted"},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/{bankAccountId}/backfill":{"parameters":[{"$ref":"#/components/parameters/bank-account-id"}],"post":{"tags":["bank-accounts"],"summary":"Backfill bank account history","description":"Imports historical bank transactions for this account from the provider over a date range, then runs matching against the account's full current card set. Unlike the `backfill` object on `PATCH /bank-accounts/{bankAccountId}` — which imports history for cards being added in that same request — this endpoint recovers a date window without touching card links.\n\nRequires a backing connection. Starting a backfill while another sync already holds the account's connection returns `409 Conflict`; retry shortly.\n\nFor Mastercard-provider accounts, `loadHistoric: true` additionally asks the provider to generate deep history (up to 2 years) for this account before the import runs. This is a billable provider operation and generation is asynchronous on the provider side: if the immediate import returns few rows, re-run the same window without the flag once generation completes (typically within minutes). Providers without a deep-history operation reject the flag with `400 Bad Request`.\n","operationId":"BackfillBankAccount","security":[{"main-auth":["banking:admin"]}],"requestBody":{"description":"Date range to import. Both bounds are optional; send an empty object for the default window.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start of the range in YYYY-MM-DD format. Defaults to 90 days ago."},"endDate":{"type":"string","format":"date","description":"End of the range in YYYY-MM-DD format. Defaults to today."},"loadHistoric":{"type":"boolean","description":"Mastercard-provider accounts only. Triggers the provider's billable deep-history generation (up to 2 years) for this account before the import. Generation is asynchronous — re-run the window without the flag if rows are missing. Providers without the capability return `400`."}}},"examples":{"BackfillDateRangeExample":{"value":{"startDate":"2026-06-13","endDate":"2026-06-27"}},"BackfillLoadHistoricExample":{"value":{"startDate":"2025-08-01","endDate":"2026-07-30","loadHistoric":true}},"BackfillDefaultWindowExample":{"value":{}}}}}},"responses":{"201":{"description":"Backfill completed","content":{"application/json":{"schema":{"type":"object","required":["id","transactionsProcessed","matchesFound"],"properties":{"id":{"type":"string","format":"uuid","description":"The bank account identifier."},"transactionsProcessed":{"type":"integer","description":"Historical bank transactions imported and processed."},"matchesFound":{"type":"integer","description":"Matches found against the account's linked cards during the backfill."}}},"examples":{"Example Backfill Bank Account Response":{"value":{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","transactionsProcessed":118,"matchesFound":27}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"409":{"$ref":"#/components/responses/banking_conflict"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/{bankAccountId}/refresh":{"parameters":[{"$ref":"#/components/parameters/bank-account-id"}],"post":{"tags":["bank-accounts"],"summary":"Refresh bank account","description":"Creates a new hosted link URL for the user to re-authenticate an account in `auth_required`. Any other state answers `400`. To ask the bank for new transactions, use `POST /bank-accounts/{bankAccountId}/transactions/refresh`.\n","operationId":"RefreshBankAccount","security":[{"main-auth":["banking:write"]}],"responses":{"201":{"description":"Refresh triggered","content":{"application/json":{"schema":{"type":"object","required":["id","hostedLink","expiresAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The bank account identifier."},"hostedLink":{"type":"string","description":"A hosted URL for the user to complete re-authentication."},"expiresAt":{"type":"string","format":"date-time","description":"When the hosted link expires."}}},"examples":{"Example Refresh Bank Account Response":{"value":{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","hostedLink":"https://hosted.plaid.com/link/refresh123","expiresAt":"2025-10-03T14:55:42.000Z"}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-accounts/{bankAccountId}/transactions/refresh":{"parameters":[{"$ref":"#/components/parameters/bank-account-id"}],"post":{"tags":["bank-accounts"],"summary":"Refresh transactions","description":"Asks the data provider to check this account's institution **now**, instead of waiting for its own schedule (typically one to four checks a day). The call returns once the check has run, usually within seconds but occasionally 30 seconds or more. It imports nothing itself: anything the check finds arrives through the normal update path within moments.\n\n**Billable per successful call.** Use it at moments that matter, not on a timer. Returns `400 Bad Request` when the account has no backing connection, or when its provider or institution doesn't support an on-demand refresh (e.g. some card issuers), and `502 Bad Gateway` when the provider's check fails.\n","operationId":"RefreshBankAccountTransactions","security":[{"main-auth":["banking:admin"]}],"responses":{"202":{"description":"The provider has run its check of the institution. `durationMs` is how long that check took, not an import; any changes it found arrive through the normal update path.","content":{"application/json":{"schema":{"type":"object","required":["id","requestedAt","durationMs"],"properties":{"id":{"type":"string","format":"uuid","description":"The bank account identifier."},"requestedAt":{"type":"string","format":"date-time","description":"When the check was requested."},"durationMs":{"type":"integer","description":"How long the provider took to run the check."}}},"examples":{"Example Refresh Bank Account Transactions Response":{"value":{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","requestedAt":"2026-10-05T00:59:10Z","durationMs":4210}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"},"502":{"$ref":"#/components/responses/banking_bad_gateway"}}}},"/bank-subscriptions":{"get":{"tags":["bank-subscriptions"],"summary":"List bank subscriptions","description":"Returns a list of bank subscriptions (active connections to financial institutions) under the account.\n\nBank subscriptions are created automatically when a bank link enrollment is completed. Each subscription represents a connection to a single financial institution.\n\nBy default, `GET /bank-subscriptions` returns subscriptions ordered by the latest `createdAt`.\n\nThis endpoint supports cursor-based pagination.\n","operationId":"ListBankSubscriptions","parameters":[{"$ref":"#/components/parameters/subaccount-id"},{"name":"state","in":"query","description":"Filter subscriptions by state","required":false,"schema":{"type":"string","enum":["active","error","auth_required","disconnected"]}},{"name":"connectionId","in":"query","description":"Filter subscriptions by provider connection identifier","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/banking-limit"},{"$ref":"#/components/parameters/cursor"}],"security":[{"main-auth":["banking:admin"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/bank-subscription"}},"pagination":{"type":"object","required":["hasMore"],"properties":{"cursor":{"type":"string","description":"Cursor to use for the next page of results."},"hasMore":{"type":"boolean","description":"Whether there are more results available."}}}}},"examples":{"Example List Bank Subscriptions Response":{"value":{"items":[{"id":"e4b7c9a2-1d3f-4e8a-9c6b-5f2d7a0e8b1c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","connectionId":"conn_abc123def456","provider":"PLAID","institutionName":"Chase","state":"active","webhook":{"url":"https://example.com/webhooks/banking","status":"confirmed"},"syncCursor":null,"createdAt":"2025-10-03T10:55:42.000Z","updatedAt":"2025-10-03T10:55:42.000Z"}],"pagination":{"hasMore":false}}}}}},"links":{"GetFirstBankSubscription":{"operationId":"GetBankSubscription","parameters":{"bankSubscriptionId":"$response.body#/items/0/id"},"description":"Retrieve the first bank subscription from the list."}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-subscriptions/{bankSubscriptionId}":{"parameters":[{"$ref":"#/components/parameters/bank-subscription-id"}],"get":{"tags":["bank-subscriptions"],"summary":"Retrieve bank subscription","description":"Returns detailed information about a specific bank subscription by its identifier, including the connection state and webhook configuration.","operationId":"GetBankSubscription","security":[{"main-auth":["banking:admin"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-subscription"},"examples":{"Example Get Bank Subscription Response":{"$ref":"#/components/examples/bank-subscription"}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-subscriptions/by-connection/{connectionId}":{"parameters":[{"$ref":"#/components/parameters/connection-id"}],"get":{"tags":["bank-subscriptions"],"summary":"Retrieve bank subscription by connection","description":"Returns a bank subscription by its provider connection identifier (e.g. Plaid item ID).\n\nThis is useful when you have the provider's connection ID and need to look up the corresponding subscription.\n","operationId":"GetBankSubscriptionByConnection","security":[{"main-auth":["banking:admin"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-subscription"},"examples":{"Example Get Bank Subscription By Connection Response":{"$ref":"#/components/examples/bank-subscription"}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-transactions/{subaccountId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}],"get":{"tags":["bank-transactions"],"summary":"List bank transactions","description":"Returns a list of bank transactions for a subaccount. Bank transactions are synced from connected financial institutions. A movement may briefly appear as its pending posting until the posted transaction replaces it (the pending row is then removed from the feed).\n\nBy default, `GET /bank-transactions/{subaccountId}` returns transactions ordered by the latest `date`.\n\nThis endpoint supports cursor-based pagination and various filters including date range, amount range, and match status.\n","operationId":"ListBankTransactions","parameters":[{"$ref":"#/components/parameters/bank-account-id-2"},{"$ref":"#/components/parameters/card-id-2"},{"$ref":"#/components/parameters/start-date"},{"$ref":"#/components/parameters/end-date"},{"$ref":"#/components/parameters/min-amount"},{"$ref":"#/components/parameters/max-amount"},{"$ref":"#/components/parameters/transaction-type"},{"$ref":"#/components/parameters/matched"},{"in":"query","name":"source","description":"Filter transactions by source.","required":false,"schema":{"type":"string","enum":["PLAID","UPLOAD","MASTERCARD_US","MASTERCARD_EU"]}},{"$ref":"#/components/parameters/banking-limit"},{"$ref":"#/components/parameters/cursor"}],"security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/bank-transaction"}},"pagination":{"type":"object","required":["hasMore"],"properties":{"cursor":{"type":"string","description":"Cursor to use for the next page of results."},"hasMore":{"type":"boolean","description":"Whether there are more results available."}}}}},"examples":{"Example List Bank Transactions Response":{"value":{"items":[{"_links":{"self":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"},"bankAccount":{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"match":{"href":"/transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"}},"id":"7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankAccountId":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","matchId":"b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e","date":"2025-10-15","amount":42.5,"currency":"USD","description":"UBER TRIP","merchantName":"Uber","category":["Travel"],"transactionType":"debit","source":"PLAID","status":"matched","settlement":null,"createdAt":"2025-10-15T14:30:00.000Z"},{"_links":{"self":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a"},"bankAccount":{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"}},"id":"2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankAccountId":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","cardId":null,"matchId":null,"date":"2025-10-14","amount":156.23,"currency":"USD","description":"AMAZON MARKETPLACE","merchantName":"Amazon","category":["Shopping"],"transactionType":"debit","source":"PLAID","status":"posted","settlement":null,"createdAt":"2025-10-14T09:15:00.000Z"}],"pagination":{"cursor":"ZXhhbXBsZQ==","hasMore":true}}}}}},"links":{"GetFirstBankTransaction":{"operationId":"GetBankTransaction","parameters":{"transactionId":"$response.body#/items/0/id"},"description":"Retrieve the first bank transaction from the list."}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-transactions/{subaccountId}/{transactionId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"},{"$ref":"#/components/parameters/transaction-id"}],"get":{"tags":["bank-transactions"],"summary":"Retrieve bank transaction","description":"Returns detailed information about a specific bank transaction by its identifier, including match status and transaction metadata.","operationId":"GetBankTransaction","security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bank-transaction"},"examples":{"Example Get Bank Transaction Response":{"$ref":"#/components/examples/bank-transaction"}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/bank-transactions/{subaccountId}/webhooks":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}],"post":{"tags":["bank-transactions"],"summary":"Trigger bank transaction webhooks","description":"Manually triggers webhook delivery for specified bank transactions. This can be used to re-emit webhooks that may have been missed or to force re-matching of transactions.\n\nYou can specify which webhook event types to emit: `banktransaction.created` for transaction data or `transaction.match.created` for match results.\n","operationId":"TriggerBankTransactionWebhooks","security":[{"main-auth":["banking:admin"]}],"requestBody":{"description":"Webhook trigger request","required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"description":"List of bank transaction identifiers to emit webhooks for. Must contain at least one ID.","type":"array","minItems":1,"items":{"type":"string","format":"uuid"}},"webhooks":{"description":"The types of webhook events to emit. Leave it out and only `banktransaction.created` is sent.","type":"array","items":{"type":"string","enum":["banktransaction.created","transaction.match.created"]}},"forceRematch":{"description":"Set to `true` to re-run the matching algorithm for the named transactions before emitting webhooks. Transactions that already have a match are genuinely re-scored: the existing match id is preserved when the pairing survives, updated when a better pairing exists, and removed when the movement no longer matches.","type":"boolean","default":false},"dispatchUnmatched":{"description":"After the re-match, emit the standalone bank-only feed entry for each named transaction the matcher left unmatched (idempotent per transaction — already-emitted standalones are skipped). Requires `forceRematch: true` and `webhooks` to include `transaction.match.created`; the request is rejected with `400` otherwise, because only a same-run re-match can distinguish a genuinely unmatched movement from a duplicate of an already-settled purchase.","type":"boolean","default":false}}},"examples":{"TriggerWebhooksExample":{"value":{"ids":["7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"],"webhooks":["banktransaction.created","transaction.match.created"],"forceRematch":false}},"RematchAndDispatchExample":{"value":{"ids":["7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"],"webhooks":["transaction.match.created"],"forceRematch":true,"dispatchUnmatched":true}}}}}},"responses":{"200":{"description":"Webhooks triggered","content":{"application/json":{"schema":{"type":"object","required":["message","emitted","resent","matched","skipped","failed"],"properties":{"message":{"type":"string","description":"Human-readable summary of the operation."},"emitted":{"type":"integer","description":"Number of webhook events emitted."},"resent":{"type":"integer","description":"Number of webhooks resent."},"matched":{"type":"integer","description":"Number of transactions that were matched."},"skipped":{"type":"integer","description":"Number of transactions that were skipped."},"failed":{"type":"array","description":"Transactions that failed to process.","items":{"type":"object","properties":{"id":{"type":"string","description":"The transaction identifier that failed."},"error":{"type":"string","description":"The error message describing why processing failed."}}}},"dispatched":{"type":"integer","description":"Number of standalone bank-only emissions dispatched for still-unmatched transactions. Only present when `dispatchUnmatched` was requested (and on service versions that support the flag)."},"dispatchError":{"type":"string","description":"Present when the standalone dispatch step failed after a successful re-match; the matching results above still stand."}}},"examples":{"Example Trigger Webhooks Response":{"value":{"message":"Processed 1 transactions","emitted":2,"resent":0,"matched":1,"skipped":0,"failed":[]}}}}}},"400":{"$ref":"#/components/responses/banking_bad_request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/transaction-matches/{subaccountId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}],"get":{"tags":["transaction-matches"],"summary":"List transaction matches","description":"Returns a list of transaction matches for a subaccount. Each match represents a link between a bank transaction and a card transaction, along with a confidence score and the reasoning behind the match.\n\nBy default, matches are filtered to `MEDIUM` confidence and above. Use the `minConfidence` parameter to adjust the threshold.\n\nBy default, `GET /transaction-matches/{subaccountId}` returns matches ordered by the latest `createdAt`.\n\nThis endpoint supports cursor-based pagination.\n","operationId":"ListTransactionMatches","parameters":[{"$ref":"#/components/parameters/bank-account-id-2"},{"$ref":"#/components/parameters/card-id-2"},{"$ref":"#/components/parameters/bank-transaction-id"},{"$ref":"#/components/parameters/card-transaction-id"},{"$ref":"#/components/parameters/min-confidence"},{"$ref":"#/components/parameters/start-date"},{"$ref":"#/components/parameters/end-date"},{"$ref":"#/components/parameters/banking-limit"},{"$ref":"#/components/parameters/cursor"}],"security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/transaction-match"}},"pagination":{"type":"object","required":["hasMore"],"properties":{"cursor":{"type":"string","description":"Cursor to use for the next page of results."},"hasMore":{"type":"boolean","description":"Whether there are more results available."}}}}},"examples":{"Example List Transaction Matches Response":{"value":{"items":[{"_links":{"self":{"href":"/transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"},"cardTransaction":{"href":"/transactions/a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d"},"bankTransaction":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"}},"id":"b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","cardTransactionId":"a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d","bankTransactionId":"7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c","confidence":"HIGH","score":0.85,"cardTransaction":{"date":"2025-10-15","amount":42.5,"currency":"USD","descriptor":"UBER TRIP"},"bankTransaction":{"date":"2025-10-15","amount":42.5,"currency":"USD","description":"UBER TRIP","merchantName":"Uber"},"reasons":[{"type":"Amount","score":1,"cardValue":"42.50","bankValue":"42.50","diff":0,"message":"Exact amount match ($42.50)"},{"type":"Date","score":0.9,"cardValue":"2025-10-15","bankValue":"2025-10-15","diff":0,"message":"Transaction dates within 1 day"},{"type":"Merchant","score":0.85,"cardValue":"UBER TRIP","bankValue":"Uber","diff":0,"message":"Merchant name contains match (Uber)"}],"createdAt":"2025-10-15T14:31:00.000Z"}],"pagination":{"hasMore":false}}}}}},"links":{"GetFirstTransactionMatch":{"operationId":"GetTransactionMatch","parameters":{"transactionMatchId":"$response.body#/items/0/id"},"description":"Retrieve the first transaction match from the list."}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"500":{"$ref":"#/components/responses/banking_server_error"}}}},"/transaction-matches/{subaccountId}/{transactionMatchId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"},{"$ref":"#/components/parameters/transaction-match-id"}],"get":{"tags":["transaction-matches"],"summary":"Retrieve transaction match","description":"Returns detailed information about a specific transaction match, including the confidence level, numeric score, and a breakdown of the scoring factors.","operationId":"GetTransactionMatch","security":[{"main-auth":["banking:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/transaction-match"},"examples":{"Example Get Transaction Match Response":{"$ref":"#/components/examples/transaction-match"}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/banking_forbidden"},"404":{"$ref":"#/components/responses/banking_not_found"},"500":{"$ref":"#/components/responses/banking_server_error"}}}}},"components":{"securitySchemes":{"main-auth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.sandbox.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token","scopes":{"accounts:write":"Accounts write resource","accounts:read":"Accounts read resource","subaccounts:write":"Subaccounts write resource","subaccounts:read":"Subaccounts read resource","card-connector-data-links:write":"card-connector-data-link resource","card-connector-consents:read":"Card Consent read resource","card-connector-consents:write":"Card Consent write resource","webhooks:read":"Read Webhook resources","webhooks:write":"Write Webhook resources","card-subscriptions:write":"Create card subscription","card-subscriptions:read":"Read card subscription","card-verifications:write":"Create card verification","card-verifications:read":"Read Card verification","cards:read":"Read Card resources","cardholder:read":"Read Cardholder resources","cardholder:write":"Write Cardholder resources","transactions:read":"Read Transaction resources","transaction-messages:read":"Read Transaction Message resources","network-bulk-feeds:read":"Read network bulk feed","network-bulk-feeds:write":"Write network bulk feed","network-bulk-enrollments:read":"Read network bulk enrollment","network-bulk-enrollments:write":"Write network bulk enrollment and confirmation, and check for an open enrollment","network-links:write":"Write network link","enrollment-methods:write":"Write enrollment methods","simulation:write":"Write sandbox simulations","banking:read":"Read banking resources","banking:write":"Write banking resources","banking:admin":"Admin banking operations","appstore:enrollment:write":"Enroll cards via the appstore B2C flow","appstore:cards:read":"View enrolled cards in the appstore","appstore:transactions:read":"View synced transactions in the appstore","appstore:transactions:sync":"Trigger transaction sync in the appstore","appstore:sessions:read":"Read appstore session state","appstore:sessions:write":"Write or delete appstore session state","appstore:tokens:read":"Read appstore stored tokens and connections","appstore:tokens:write":"Write appstore stored tokens and connections"}}}}},"parameters":{"subaccount-id":{"in":"query","name":"subaccountId","required":false,"schema":{"type":"string","format":"uuid"},"example":"2fd4d402-b759-479c-87a6-58d85e345356"},"subaccount-id-2":{"in":"path","name":"subaccountId","required":true,"schema":{"type":"string","format":"uuid"},"example":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"},"transaction-id":{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"},"example":"9340721f-bdce-4afa-bd9d-26cceb9d2176"},"bank-link-state":{"in":"query","name":"state","description":"Filter bank links by state","required":false,"schema":{"type":"string","enum":["pending","completed","expired"]},"example":"completed"},"banking-limit":{"in":"query","name":"limit","description":"Maximum number of items to return","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":250},"example":250},"cursor":{"in":"query","name":"cursor","required":false,"description":"The cursor to use for pagination. Identifies your place on the list","schema":{"type":"string","format":"byte"},"example":"ZXhhbXBsZQ=="},"bank-link-id":{"in":"path","name":"bankLinkId","description":"The client-provided identifier of the bank link.","required":true,"schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$"},"example":"enrollment_792dcb7d"},"bank-account-state":{"in":"query","name":"state","description":"Filter bank accounts by state","required":false,"schema":{"type":"string","enum":["active","auth_required","disconnected"]},"example":"active"},"card-id-2":{"in":"query","name":"cardId","required":false,"schema":{"type":"string","format":"uuid"},"example":"8164683a-8d23-4421-9694-1a81fc9b9c37"},"bank-account-id":{"in":"path","name":"bankAccountId","required":true,"schema":{"type":"string","format":"uuid"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"bank-subscription-id":{"in":"path","name":"bankSubscriptionId","required":true,"schema":{"type":"string","format":"uuid"},"example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"connection-id":{"in":"path","name":"connectionId","required":true,"schema":{"type":"string"},"example":"conn_abc123def456"},"bank-account-id-2":{"in":"query","name":"bankAccountId","required":false,"description":"Filter to subscriptions whose card materialized from this bank account (bank-derived subscriptions).","schema":{"type":"string","format":"uuid"},"example":"2b9c1e77-5a3d-4c8b-9f21-6d0e4a7b8c90"},"start-date":{"in":"query","name":"startDate","description":"Filter results from this date (inclusive), in YYYY-MM-DD format","required":false,"schema":{"type":"string","format":"date"},"example":"2025-10-01"},"end-date":{"in":"query","name":"endDate","description":"Filter results up to this date (inclusive), in YYYY-MM-DD format","required":false,"schema":{"type":"string","format":"date"},"example":"2025-10-31"},"min-amount":{"in":"query","name":"minAmount","description":"Filter transactions with an amount greater than or equal to this value","required":false,"schema":{"type":"number"},"example":10},"max-amount":{"in":"query","name":"maxAmount","description":"Filter transactions with an amount less than or equal to this value","required":false,"schema":{"type":"number"},"example":500},"transaction-type":{"in":"query","name":"transactionType","description":"Filter bank transactions by transaction type","required":false,"schema":{"type":"string","enum":["debit","credit"]},"example":"debit"},"matched":{"in":"query","name":"matched","description":"Filter bank transactions by match status. Set to `true` to return only matched transactions, or `false` for unmatched.","required":false,"schema":{"type":"string","enum":["true","false"]},"example":"true"},"bank-transaction-id":{"in":"query","name":"bankTransactionId","description":"Filter by bank transaction identifier","required":false,"schema":{"type":"string","format":"uuid"},"example":"7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"},"card-transaction-id":{"in":"query","name":"cardTransactionId","description":"Filter by card transaction identifier","required":false,"schema":{"type":"string","format":"uuid"},"example":"a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d"},"min-confidence":{"in":"query","name":"minConfidence","description":"Filter transaction matches by minimum confidence level. Defaults to `MEDIUM`, which returns HIGH and MEDIUM matches.","required":false,"schema":{"type":"string","enum":["HIGH","MEDIUM","LOW"],"default":"MEDIUM"},"example":"MEDIUM"},"transaction-match-id":{"in":"path","name":"transactionMatchId","required":true,"schema":{"type":"string","format":"uuid"},"example":"c3d4e5f6-a7b8-9012-cdef-123456789012"}},"schemas":{"link":{"type":"object","properties":{"href":{"type":"string"},"templated":{"type":"boolean"},"type":{"type":"string"},"deprecation":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string"},"title":{"type":"string"},"hreflang":{"type":"string"}},"required":["href"]},"bank-link":{"type":"object","required":["_links","id","accountId","subaccountId","state","hostedLink","linkExpiresAt","createdAt"],"properties":{"_links":{"type":"object","description":"HAL-style links to related resources.","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"bankAccounts":{"type":"array","description":"Links to the bank accounts created from this link. Only present when state is `completed` and accounts exist.","items":{"$ref":"#/components/schemas/link"}}}},"id":{"type":"string","description":"The client-provided identifier of the bank link. Must be alphanumeric with hyphens and underscores only.","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$"},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account that owns this bank link."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount associated with this bank link."},"state":{"type":"string","description":"Current state of the bank link.\n- `pending`: The link has been created and is awaiting user enrollment.\n- `completed`: The user has successfully connected their bank account.\n- `expired`: The link has expired without being completed.\n","enum":["pending","completed","expired"]},"provider":{"type":"string","description":"Open-banking provider this link was created on. Fixed at creation: every later operation on the link uses this value. Links created before provider selection existed are `plaid`.\n","enum":["plaid","mastercard"]},"hostedLink":{"type":"string","nullable":true,"description":"The hosted URL where the user can complete the bank enrollment. This link expires after 4 hours and is automatically refreshed when retrieved via GET."},"linkExpiresAt":{"description":"Date and time when the hosted link expires, in UTC, following ISO 8601 format.","type":"string","format":"date-time","nullable":true},"completedAt":{"description":"Date and time when the bank link enrollment was completed, in UTC, following ISO 8601 format. Only present when state is `completed`.","type":"string","format":"date-time"},"lastRejection":{"type":"object","nullable":true,"description":"Present while `state` is `pending` after a completion attempt was refused because the connected institution is not allowed for this link (for example, a non-Amex institution on an Amex-restricted link). The link can still be completed by reconnecting with an allowed institution — a successful completion clears this field.\n","properties":{"institutionName":{"type":"string","nullable":true,"description":"Display name of the refused institution."},"at":{"type":"string","format":"date-time","description":"When the refusal happened, in UTC, following ISO 8601 format."}}},"lastMintFailure":{"type":"object","nullable":true,"description":"Present once a completion attempt was aborted because card creation (the `bank-feed` mint) failed for one or more discovered credit accounts. The link stays pending and completion is retried; a later successful completion clears this field (an expired link keeps its last failure). `transient` failures resolve on retry; a `permanent` one keeps aborting until investigated.\n","properties":{"at":{"type":"string","format":"date-time","description":"When the failed completion attempt happened, in UTC, following ISO 8601 format."},"kind":{"type":"string","enum":["permanent","transient"],"description":"Whether the underlying failure is expected to clear on retry."},"failedAccountCount":{"type":"integer","description":"How many discovered credit accounts failed to mint on the attempt."}}},"filters":{"type":"object","description":"The account filtering actually applied to this link, after resolution against the account's bank-linking policy. Echoes what the hosted session will offer; absent on links created before filtering existed.\n","properties":{"accountTypes":{"type":"array","description":"Account types selectable in the hosted session.","items":{"type":"string","enum":["checking","savings","credit"]}},"linkCustomizationName":{"type":"string","description":"The Plaid Link customization this link asked for: the request's `filters.linkCustomizationName`, or else the bank-linking policy's `plaidLinkCustomizationName`. Absent when neither applies. When Plaid refused `amex_only` and the create was retried without it, this still reads `amex_only`, and the link's completion is still held to American Express institutions.\n"}}},"bankAccounts":{"type":"array","description":"Summary of bank accounts created from this link. Only present when state is `completed` and accounts exist.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The bank account identifier."},"name":{"type":"string","description":"The display name of the bank account."},"institutionName":{"type":"string","nullable":true,"description":"Display name of the connected institution. Present on this API response; not included on the `banklink.completed` event payload.\n"},"mask":{"type":"string","nullable":true,"description":"Last 4 digits of the account number. For `credit` accounts this is the card number's last 4 — the per-card identity for bank-connected (e.g. American Express) enrollments. Not guaranteed per-card when the institution combines multiple cards into one account.\n"},"type":{"type":"string","nullable":true,"description":"Normalized account type (e.g. `checking`, `savings`, `credit`)."},"cardIds":{"type":"array","description":"Identifiers of already-enrolled cards linked to this account, matched when an enrolled card's last 4 equals a credit account's mask (applied at completion and by a scheduled sweep that re-checks each cardless credit account every few hours). A link is an association to an EXISTING card, not a new enrollment.\n","items":{"type":"string","format":"uuid"}},"cards":{"type":"array","description":"Cards created from this account at completion (`bank-feed` enrollments), each paired with its subscription. Present only on credit accounts that created a card; a created card also appears in `cardIds`.\n","items":{"type":"object","required":["id","subscriptionId","last4digits","network","enrollmentType"],"properties":{"id":{"type":"string","format":"uuid"},"subscriptionId":{"type":"string","format":"uuid"},"last4digits":{"type":"string","pattern":"^\\d{4}$"},"network":{"type":"string","nullable":true},"enrollmentType":{"type":"string","enum":["bank-feed"]}}}},"noLinkReason":{"type":"string","nullable":true,"description":"Why this credit account has no card. Present on this API response; not included on the `banklink.completed` event payload. Present ONLY while the account is still cardless — once any card links, the field disappears.\n\nA credit account can legitimately finish linking with no card, and this says which case it was rather than leaving an unexplained empty `cardIds`:\n  - `bulk_card_owns_mask`: a bulk-enrolled card is the live owner of this last 4. It correctly suppresses a duplicate card, and a bulk subscription cannot take an automatic bank-account link.\n  - `mask_ambiguous_accounts`: several accounts on this link share the mask, so no automatic link is safe.\n  - `mask_ambiguous_cards`: several enrolled cards share the mask, and card-number (BIN) evidence could not narrow them to one.\n  - `card_linked_elsewhere`: the matching card is already linked to another bank account.\n  - `card_not_attachable`: the matching card has no active subscription to attach to.\n  - `no_institution_id`: the provider reported no institution, so no stable card identity can be derived.\n  - `mask_matches_no_plausible_card`: enrolled cards share the mask, but BIN evidence ruled every one of them out for the connected institution (wrong issuing bank, or debit/prepaid funding), so nothing linked rather than linking a known-wrong card.\n\nThe scheduled mask sweep and a manual `PATCH cardIds` both remain available; the field describes the state at completion, not a permanent verdict.\n","enum":["bulk_card_owns_mask","mask_ambiguous_accounts","mask_ambiguous_cards","card_linked_elsewhere","card_not_attachable","no_institution_id","mask_matches_no_plausible_card"]}}}},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"banking-error":{"type":"object","description":"The error body of the Banking API: plain JSON with `statusCode` and `message`. The card APIs use a different body (`title` and `detail`). Branch on `code` where a refusal carries one; `message` is text for people.\n\nOne exception: a `401` for a missing or invalid token comes from the gateway, before the request reaches the Banking API, and carries `title` and `detail` like the card APIs.\n","properties":{"statusCode":{"type":"integer","description":"The HTTP status code of the answer, repeated in the body.","example":404},"message":{"type":"string","description":"What went wrong, in words. Some messages carry ids or states, so do not parse it.","example":"Subaccount not found for this account"},"code":{"type":"string","description":"A stable name for the refusal, such as `SUBACCOUNT_NOT_FOUND`. Present on some refusals only.","example":"SUBACCOUNT_NOT_FOUND"},"error":{"type":"string","description":"The name of the HTTP status, such as `Not Found`. Present on some refusals only.","example":"Not Found"},"reason":{"type":"string","description":"Why the refusal happened, on the refusals that name one. For example, `BANK_ENROLLMENT_DISABLED` carries `network-not-allowed` when the account's setting does not allow a bank link for that card network.","example":"network-not-allowed"},"errors":{"type":"array","description":"The validation problems, on a `400` for a request that did not pass validation. Each item has a `path`, the place of the field in the request; its other fields come from the validation library and can change.","items":{"type":"object"},"example":[{"path":["id"],"code":"invalid_type","message":"Invalid input: expected string, received undefined"}]}},"required":["statusCode","message"]},"bank-link-consent":{"type":"object","description":"The bank-link consent record. The Unified Enrollment SDK sets it on channel `sdk-unified`, naming the Astrada consent text of the bank-connect screen the person saw. Integrators do not send it. Astrada relays it to each card subscription the bank link creates, where it is recorded and never refused. A consent without `textVersionId` is accepted but not kept.\n","required":["channel"],"properties":{"channel":{"type":"string","enum":["sdk-unified"],"description":"Always `sdk-unified`."},"textVersionId":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z0-9-]+:[A-Za-z0-9:._-]+@v?\\d+$","description":"The id of the bank-connect consent text the SDK showed, such as `sdk-unified:bank-consent.plaid.bank.en@v1`."},"textHash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$","description":"`sha256:` and the lowercase hex SHA-256 of the text named by `textVersionId`, compared with the registered text when sent."},"sdkVersion":{"type":"string","maxLength":60,"pattern":"^(unified-sdk|legacy-sdk)@(v\\d+\\.\\d+\\.\\d+|preview-[0-9a-f]{7,40}|local)$","description":"The SDK release that collected the consent."},"variables":{"type":"object","maxProperties":10,"description":"`companyName` and `providerName`, as the screen showed them. For a Plaid link, Astrada adds `plaidLinkSessionId` when it relays the record.\n","additionalProperties":{"type":"string","maxLength":500}}}},"bank-account":{"type":"object","required":["_links","id","accountId","subaccountId","externalId","institutionName","cardIds","cards","name","currency","type","state","createdAt","updatedAt"],"properties":{"_links":{"type":"object","description":"HAL-style links to related resources.","required":["self","transactions"],"properties":{"self":{"$ref":"#/components/schemas/link"},"transactions":{"$ref":"#/components/schemas/link"},"bankLink":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of the bank account."},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account that owns this bank account."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount associated with this bank account."},"bankLinkId":{"type":"string","nullable":true,"description":"The identifier of the bank link that created this account. Null for accounts that predate persisted link attribution."},"externalId":{"type":"string","description":"The provider account ID for the connected account."},"cardIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The identifiers of cards linked to this bank account for transaction matching, always current. A card links when its last 4 digits match this account's mask (the same rule applied at bank-link completion and by a scheduled sweep that re-checks each cardless credit account every few hours), or when set manually via PATCH. Cards must belong to the same subaccount."},"noLinkReason":{"type":"string","nullable":true,"description":"Why this credit account has no card. Present ONLY while the account is still cardless — once any card links, the field disappears, so it can never contradict `cardIds`. See the identically-named field on the bank link response for the full meaning of each value.\n","enum":["bulk_card_owns_mask","mask_ambiguous_accounts","mask_ambiguous_cards","card_linked_elsewhere","card_not_attachable","no_institution_id","mask_matches_no_plausible_card"]},"cards":{"type":"array","description":"Cards MATERIALIZED from this bank account (`bank-feed` enrollments minted at bank-link completion for credit accounts whose mask matched no already-enrolled card). Distinct from `cardIds`, which is the link surface: a mask-matched card appears in `cardIds` only, while a minted card appears in both. Empty for depository and mask-matched-only accounts.\n","items":{"type":"object","required":["id","subscriptionId","last4digits","network","enrollmentType"],"properties":{"id":{"type":"string","format":"uuid","description":"The minted card's identifier on the cards platform."},"subscriptionId":{"type":"string","format":"uuid","description":"The bank-feed card subscription created by the mint."},"last4digits":{"type":"string","pattern":"^\\d{4}$","description":"The card number's last 4 — equals this account's mask by construction."},"network":{"type":"string","nullable":true,"description":"The card network when the institution implies it (e.g. `amex`); null until a PAN enrollment upgrades the card in place."},"enrollmentType":{"type":"string","enum":["bank-feed"],"description":"Always `bank-feed` — the enrollment transport this card was materialized through."}}}},"institutionName":{"type":"string","description":"The name of the connected financial institution."},"institutionId":{"type":"string","nullable":true,"description":"The provider identifier of the connected institution (Plaid `ins_*`). Null for connections made before this field was captured."},"name":{"type":"string","description":"The display name of the bank account (e.g. \"Checking\", \"Savings\")."},"mask":{"type":"string","nullable":true,"description":"The last 4 digits of the account number. For `credit` accounts this is the card number's last 4 — the per-card identity for bank-connected (e.g. American Express) card enrollments. Not guaranteed to be per-card when the institution combines multiple cards into a single account."},"type":{"type":"string","description":"The normalized type of bank account. (Correction — the service has always returned normalized values; the previous `depository`/`credit` enum understated live behavior. Codegen consumers should regenerate.)","enum":["checking","savings","prepaid","credit","loan","investment","other"]},"subtype":{"type":"string","nullable":true,"description":"The raw provider account subtype (e.g. Plaid `credit card`, `checking`). Null when the provider did not supply one or for accounts connected before this field was captured."},"currency":{"type":"string","description":"The currency of the account following ISO 4217 format.","minLength":3,"maxLength":3},"state":{"type":"string","description":"Current state of the bank account.\n- `active`: The account is connected and functioning normally.\n- `auth_required`: The account requires re-authentication.\n- `disconnected`: The account has been disconnected from the provider.\n","enum":["active","auth_required","disconnected"]},"subscriptionState":{"type":"string","nullable":true,"description":"The health of the underlying aggregator connection backing this account. The account `state` above can read `active` while the connection has errored or needs re-auth, so this field can read \"active but dead\". Null if no subscription is linked.\n","enum":["active","error","auth_required","disconnected"]},"lastSyncedAt":{"description":"Last successful sync of the backing connection, in UTC, following ISO 8601 format. Pairs with `subscriptionState` as the freshness signal. Null until the first sync.","type":"string","format":"date-time","nullable":true},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"bank-subscription":{"type":"object","required":["id","accountId","subaccountId","connectionId","provider","institutionName","state","webhook","syncCursor","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the bank subscription."},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account that owns this subscription."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount associated with this subscription."},"connectionId":{"type":"string","description":"The provider's unique connection identifier (e.g. Plaid item ID)."},"provider":{"type":"string","description":"The banking data provider for this subscription.\n- `PLAID`: Connected through Plaid.\n- `MASTERCARD_US`: Connected through Mastercard Open Finance US. Sandbox only.\n- `MASTERCARD_EU`: Connected through Mastercard Open Finance Europe. Sandbox only.\n","enum":["PLAID","MASTERCARD_US","MASTERCARD_EU"]},"institutionName":{"type":"string","description":"The name of the connected financial institution."},"state":{"type":"string","description":"Current state of the subscription.\n- `active`: The connection is functioning normally.\n- `error`: The connection has encountered an error.\n- `auth_required`: The connection requires user re-authentication.\n- `disconnected`: The connection has been disconnected.\n","enum":["active","error","auth_required","disconnected"]},"webhook":{"type":"object","description":"Webhook configuration for this subscription.","required":["url","status"],"properties":{"url":{"type":"string","nullable":true,"description":"The URL where webhook events will be delivered."},"status":{"type":"string","description":"The current status of the webhook configuration.\n- `pending`: The webhook URL has been set but not yet confirmed by the provider.\n- `confirmed`: The provider has acknowledged the webhook URL.\n- `none`: No webhook URL has been configured.\n","enum":["pending","confirmed","none"]}}},"syncCursor":{"type":"string","nullable":true,"description":"The current transaction sync cursor for this subscription."},"lastSyncedAt":{"description":"Last successful sync of this connection, in UTC, following ISO 8601 format. Null until the first sync.","type":"string","format":"date-time","nullable":true},"authErrorFirstSeenAt":{"description":"When a sync first found that the bank needs the user to sign in again, in UTC, following ISO 8601 format. Null when no such error is open.","type":"string","format":"date-time","nullable":true},"institutionLastCheckedAt":{"description":"When the bank data provider last reached the bank for this connection, in UTC, following ISO 8601 format. Null when the provider gives no such time.","type":"string","format":"date-time","nullable":true},"institutionLastFailedAt":{"description":"When the bank data provider last failed to reach the bank for this connection, in UTC, following ISO 8601 format. Null when the provider gives no such time.","type":"string","format":"date-time","nullable":true},"institutionHealth":{"type":"object","nullable":true,"description":"The bank data provider's health figures for this connection's bank. Null when the provider publishes none.","properties":{"success":{"type":"number","description":"The share of the provider's recent transaction updates for this bank that succeeded, from 0 to 1."},"errorInstitution":{"type":"number","description":"The share that failed because of the bank, from 0 to 1."},"errorProvider":{"type":"number","description":"The share that failed because of the provider, from 0 to 1."},"refreshInterval":{"type":"string","nullable":true,"description":"Whether the provider is refreshing this bank on schedule (`NORMAL`), late (`DELAYED`) or not at all (`STOPPED`).","enum":["NORMAL","DELAYED","STOPPED",null]},"incidents":{"type":"array","description":"The provider's published outages and maintenance for this bank.","items":{"type":"object","properties":{"title":{"type":"string","description":"The provider's title for the incident."},"startedAt":{"type":"string","description":"When the incident started, as the provider published it."},"endedAt":{"type":"string","nullable":true,"description":"When the incident ended, as the provider published it. Null while it is open."},"status":{"type":"string","nullable":true,"description":"The status on the provider's latest update to the incident."},"update":{"type":"string","nullable":true,"description":"The text of the provider's latest update to the incident."}}}},"observedAt":{"type":"string","format":"date-time","description":"When Astrada read these figures, in UTC, following ISO 8601 format."}}},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"bank-transaction":{"type":"object","required":["_links","id","accountId","subaccountId","bankAccountId","cardId","matchId","date","amount","currency","description","merchantName","category","transactionType","source","status","settlement","createdAt"],"properties":{"_links":{"type":"object","description":"HAL-style links to related resources.","required":["self","bankAccount"],"properties":{"self":{"$ref":"#/components/schemas/link"},"bankAccount":{"$ref":"#/components/schemas/link"},"card":{"$ref":"#/components/schemas/link"},"match":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of the bank transaction."},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account that owns this transaction."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount associated with this transaction."},"bankAccountId":{"type":"string","format":"uuid","description":"The unique identifier of the bank account this transaction belongs to."},"cardId":{"type":"string","format":"uuid","nullable":true,"description":"The card whose card transaction this bank transaction is matched to. Stamped when a match is persisted and cleared if a later forced rematch supersedes that match, so it is only ever non-null alongside `matchId`. Null while unmatched — including on accounts with linked cards: linking alone never attributes individual bank transactions.\n"},"matchId":{"type":"string","format":"uuid","nullable":true,"description":"The identifier of the transaction match, if this bank transaction has been matched to a card transaction."},"date":{"type":"string","format":"date","description":"The date the transaction was posted, in YYYY-MM-DD format."},"amount":{"type":"number","description":"The transaction amount."},"currency":{"type":"string","description":"The currency of the transaction following ISO 4217 format.","minLength":3,"maxLength":3},"description":{"type":"string","nullable":true,"description":"The transaction description provided by the financial institution."},"merchantName":{"type":"string","nullable":true,"description":"The name of the merchant."},"category":{"type":"array","nullable":true,"description":"The transaction categories assigned by the provider.","items":{"type":"string"}},"transactionType":{"type":"string","description":"The type of transaction.\n- `debit`: Money sent (outflow).\n- `credit`: Money received (inflow).\n","enum":["debit","credit"]},"source":{"type":"string","description":"The source of this transaction.\n- `PLAID`: Synced from a connected financial institution via Plaid.\n- `UPLOAD`: Imported from a manually uploaded bank statement.\n- `MASTERCARD_US`: Synced from a connected financial institution via Mastercard Open Finance US. Sandbox only.\n- `MASTERCARD_EU`: Synced from a connected financial institution via Mastercard Open Finance Europe. Sandbox only.\n","enum":["PLAID","UPLOAD","MASTERCARD_US","MASTERCARD_EU"]},"status":{"type":"string","description":"The lifecycle stage of the bank movement, derived from its match pointer and settlement state.\n- `posted`: Synced, not yet matched.\n- `matched`: Paired to a card transaction without an early settlement of its own (e.g. connector off, or a below-HIGH match) — the movement is represented by the card transaction's network settlement, and any standalone it previously emitted is netted to zero.\n- `settled`: A bank-only movement settled standalone on the unified feed.\n- `early_cleared`: A matched movement settled its card transaction early.\n- `superseded`: A previously bank-only movement was retracted or corrected.\n","enum":["posted","matched","settled","early_cleared","superseded"]},"settlement":{"type":"object","nullable":true,"description":"Settlement outcome on the unified transaction feed. Present when the movement has settled live; null otherwise (unmatched, connector off, or shadow-only).","required":["state","emissionType","emittedAt","supersededAt"],"properties":{"state":{"type":"string","enum":["settled","early_cleared","superseded"]},"emissionType":{"type":"string","enum":["early_clearing","bank_only"]},"emittedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the settlement was emitted to the feed."},"supersededAt":{"type":"string","format":"date-time","nullable":true,"description":"When the settlement was superseded or corrected, if applicable."}}},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"transaction-match":{"type":"object","required":["_links","id","accountId","subaccountId","cardTransactionId","bankTransactionId","confidence","score","cardTransaction","bankTransaction","reasons","createdAt"],"properties":{"_links":{"type":"object","description":"HAL-style links to related resources.","required":["self","cardTransaction","bankTransaction"],"properties":{"self":{"$ref":"#/components/schemas/link"},"cardTransaction":{"$ref":"#/components/schemas/link"},"bankTransaction":{"$ref":"#/components/schemas/link"},"card":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of the transaction match."},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account that owns this match."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount associated with this match."},"cardTransactionId":{"type":"string","format":"uuid","description":"The identifier of the matched card transaction message (the message the bank posting was matched against, for example the authorization). It is the `id` carried by `transactionmessage.created` and appears in `_embedded.messages[].id` on the unified transaction; it is not the unified transaction's own `id`."},"bankTransactionId":{"type":"string","format":"uuid","description":"The unique identifier of the matched bank transaction."},"confidence":{"type":"string","description":"The confidence level of the match.\n- `HIGH`: Score >= 0.70\n- `MEDIUM`: Score >= 0.50\n- `LOW`: Score >= 0.20\n","enum":["HIGH","MEDIUM","LOW"]},"score":{"type":"number","description":"The numeric match score between 0 and 1, representing how closely the bank and card transactions match.","minimum":0,"maximum":1},"cardTransaction":{"type":"object","description":"Summary of the matched card transaction.","properties":{"cardId":{"type":"string","format":"uuid","nullable":true,"description":"The card identifier associated with the matched card transaction."},"date":{"type":"string","description":"The transaction date."},"amount":{"type":"number","description":"The transaction amount."},"currency":{"type":"string","description":"The transaction currency."},"descriptor":{"type":"string","description":"The merchant descriptor."}}},"bankTransaction":{"type":"object","description":"Summary of the matched bank transaction.","properties":{"date":{"type":"string","description":"The transaction date."},"amount":{"type":"number","description":"The transaction amount."},"currency":{"type":"string","description":"The transaction currency."},"description":{"type":"string","description":"The transaction description."},"merchantName":{"type":"string","nullable":true,"description":"The merchant name."}}},"reasons":{"type":"array","description":"Breakdown of the scoring factors that contributed to the match score.","items":{"type":"object","properties":{"type":{"type":"string","description":"The matching factor type.","enum":["Amount","Date","Merchant","ReferenceId","PreAuth"]},"score":{"type":"number","description":"The individual score for this factor."},"cardValue":{"description":"The value from the card transaction used for comparison. May be a string or numeric value.","type":"string","nullable":true},"bankValue":{"description":"The value from the bank transaction used for comparison. May be a string or numeric value.","type":"string","nullable":true},"diff":{"type":"number","description":"The numeric difference between the card and bank values."},"message":{"type":"string","description":"Human-readable explanation of the score for this factor."}}}},"createdAt":{"description":"Date and time when this match was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}}},"responses":{"banking_bad_request":{"description":"The request was refused. `message`, and `code` where present, say why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"examples":{"Invalid request":{"value":{"statusCode":400,"message":"Invalid cardId","error":"Bad Request"}},"Refusal with a code":{"value":{"statusCode":400,"code":"INVALID_CURSOR","message":"Invalid cursor format"}}}}}},"unauthorized":{"description":"Authentication credentials were either missing or incorrect","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Unauthorized"]}},"required":["detail","title"]},"example":{"title":"Unauthorized","detail":"Authentication credentials were either missing or incorrect."}}}},"banking_forbidden":{"description":"The token does not hold a scope this route needs, or the account is not set up for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"example":{"statusCode":403,"message":"Insufficient permissions. Required scopes: banking:admin","error":"Forbidden"}}}},"banking_server_error":{"description":"The service failed while handling the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"example":{"statusCode":500,"message":"Internal server error"}}}},"banking_not_found":{"description":"The resource was not found for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"example":{"statusCode":404,"message":"Bank account not found","error":"Not Found"}}}},"banking_conflict":{"description":"The resource is not in a state that allows this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"example":{"statusCode":409,"message":"Bank link 3fa85f64-5717-4562-b3fc-2c963f66afa6 is not completed. Current state: pending"}}}},"banking_bad_gateway":{"description":"The bank data provider failed to complete the request. Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/banking-error"},"example":{"statusCode":502,"message":"Provider refresh failed; try again later","error":"Bad Gateway"}}}}},"examples":{"bank-link":{"description":"Example of a completed Bank Link resource","value":{"_links":{"self":{"href":"/bank-links/enrollment_792dcb7d"},"bankAccounts":[{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"}]},"id":"enrollment_792dcb7d","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","state":"completed","hostedLink":null,"linkExpiresAt":null,"completedAt":"2025-10-03T10:55:42.000Z","bankAccounts":[{"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","name":"Credit Card","mask":"4001","type":"credit","cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"]}],"createdAt":"2025-10-03T10:25:27.069Z"}},"bank-account":{"description":"Example of a Bank Account resource","value":{"_links":{"self":{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"transactions":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11?bankAccountId=3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"bankLink":{"href":"/bank-links/enrollment_792dcb7d"}},"id":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankLinkId":"enrollment_792dcb7d","externalId":"plaid_acc_792dcb7d","cardIds":["5dec2c49-0aa5-4683-a317-427eb5d115f3"],"cards":[],"institutionName":"Chase","name":"Checking","mask":"1234","type":"checking","currency":"USD","state":"active","subscriptionState":"active","lastSyncedAt":"2025-10-03T11:12:07.000Z","createdAt":"2025-10-03T10:55:42.000Z","updatedAt":"2025-10-03T10:55:42.000Z"}},"bank-subscription":{"description":"Example of a Bank Subscription resource","value":{"id":"e4b7c9a2-1d3f-4e8a-9c6b-5f2d7a0e8b1c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","connectionId":"conn_abc123def456","provider":"PLAID","institutionName":"Chase","state":"active","webhook":{"url":"https://example.com/webhooks/banking","status":"confirmed"},"syncCursor":null,"createdAt":"2025-10-03T10:55:42.000Z","updatedAt":"2025-10-03T10:55:42.000Z"}},"bank-transaction":{"description":"Example of a Bank Transaction resource","value":{"_links":{"self":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"},"bankAccount":{"href":"/bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"match":{"href":"/transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"}},"id":"7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","bankAccountId":"3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","matchId":"b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e","date":"2025-10-15","amount":42.5,"currency":"USD","description":"UBER TRIP","merchantName":"Uber","category":["Travel"],"transactionType":"debit","source":"PLAID","status":"early_cleared","settlement":{"state":"early_cleared","emissionType":"early_clearing","emittedAt":"2025-10-15T15:00:00.000Z","supersededAt":null},"createdAt":"2025-10-15T14:30:00.000Z"}},"transaction-match":{"description":"Example of a Transaction Match resource","value":{"_links":{"self":{"href":"/transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"},"cardTransaction":{"href":"/transaction-messages/a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d"},"bankTransaction":{"href":"/bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"}},"id":"b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e","accountId":"8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c","subaccountId":"1fcb895e-9217-4a6f-9d10-5a7dcef86c11","cardTransactionId":"a9b8c7d6-e5f4-3a2b-1c0d-9e8f7a6b5c4d","bankTransactionId":"7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c","confidence":"HIGH","score":0.85,"cardTransaction":{"cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","date":"2025-10-15","amount":42.5,"currency":"USD","descriptor":"UBER TRIP"},"bankTransaction":{"date":"2025-10-15","amount":42.5,"currency":"USD","description":"UBER TRIP","merchantName":"Uber"},"reasons":[{"type":"Amount","score":1,"cardValue":"42.50","bankValue":"42.50","diff":0,"message":"Exact amount match ($42.50)"},{"type":"Date","score":0.9,"cardValue":"2025-10-15","bankValue":"2025-10-15","diff":0,"message":"Transaction dates within 1 day"},{"type":"Merchant","score":0.85,"cardValue":"UBER TRIP","bankValue":"Uber","diff":0,"message":"Merchant name contains match (Uber)"}],"createdAt":"2025-10-15T14:31:00.000Z"}}}},"x-readme":{"proxy-enabled":false,"metrics-enabled":false}}