AgentaOS Bank Accounts API

openapi: 3.2.0
info:
  title: Agentaos Ai Bank Accounts API
  version: 1.0.0
  contact:
    name: AgentaOS
    url: https://agentaos.ai
  license:
    name: Proprietary
    url: https://agentaos.ai
  description: 'Operations tagged Bank Accounts across 2 of this provider''s published API definitions: agentaos-ai-openapi.json, openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentaos.ai/api/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Bank Accounts
  description: 'Where payouts go: the bank accounts of a business, as thin references (holder, last four digits, the name-check result), never the account number. For a platform: with the `AgentaOS-Account` header these act on a business you manage, once we have opened bank accounts by API for your platform. Adding an account needs a live key.'
paths:
  /gateway/bank-accounts/requirements:
    get:
      tags:
      - Bank Accounts
      operationId: getBankAccountRequirements
      summary: Get the fields a currency needs
      description: The form schema for a bank account in this currency. Render it, then send the answers to `POST /gateway/bank-accounts`. Works with a test or a live key.
      parameters:
      - name: currency
        in: query
        required: true
        schema:
          type: string
        description: The payout currency. EUR and USD are supported.
      responses:
        '200':
          description: The fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountRequirements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotYourBusiness'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/bank-accounts/requirements/refresh:
    post:
      tags:
      - Bank Accounts
      operationId: refreshBankAccountRequirements
      summary: Refresh the fields after an answer
      description: Some answers change the fields that follow (a field marked `refreshRequirementsOnChange`, such as the legal type). Send the `quoteId` and the answers so far; the fields come back updated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quoteId:
                  type: string
                details:
                  type: object
                  additionalProperties: true
              required:
              - quoteId
              - details
      responses:
        '201':
          description: The fields, updated.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotYourBusiness'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/bank-accounts:
    get:
      tags:
      - Bank Accounts
      operationId: listBankAccounts
      summary: List bank accounts
      description: The active bank accounts of the business, thin references only, each with whether the next payout can go to it.
      responses:
        '200':
          description: The accounts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotYourBusiness'
    post:
      tags:
      - Bank Accounts
      operationId: createBankAccount
      summary: Add a bank account
      description: 'Save a bank account for the business. Where the bank offers a name check, it runs at once: a clear mismatch is saved but never paid, and `payableReason` says so. Needs a live key. For a platform acting on a business it manages, bank accounts by API must have been opened for your platform; ask us. Every account added through a platform''s key is emailed to the platform''s owner and to the business''s owner. The account number is never stored: we keep the last four characters and a hash.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankAccountParams'
            example:
              currency: EUR
              type: iban
              accountHolderName: Seller GmbH
              legalType: BUSINESS
              details:
                IBAN: DE89370400440532013000
      responses:
        '201':
          description: The saved account, as a thin reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          description: 'The form was refused: `RECIPIENT_INVALID`, with one entry per field.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 400
                  code:
                    type: string
                    example: RECIPIENT_INVALID
                  message:
                    type: string
                  fieldErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          example: details.IBAN
                        message:
                          type: string
                          example: Not a valid IBAN.
                      required:
                      - path
                      - message
                required:
                - statusCode
                - code
                - fieldErrors
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankAccountsForbidden'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/bank-accounts/{id}:
    delete:
      tags:
      - Bank Accounts
      operationId: deactivateBankAccount
      summary: Retire a bank account
      description: The account stops being paid to. A currency that pointed at it falls back to the newest payable account. Needs a live key; the same platform rule as adding one.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Retired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankAccountsForbidden'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
components:
  schemas:
    BankAccountRequirements:
      type: object
      description: 'The fields a bank account in this currency needs, as a form schema: one entry per account type (`iban` for EUR, `aba` for USD), each with its fields, their validation and whether changing one refreshes the rest.'
      properties:
        quoteId:
          type: string
          description: Pass back to `requirements/refresh` when a field marked `refreshRequirementsOnChange` changes.
        requirements:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
      - quoteId
      - requirements
    CreateBankAccountParams:
      type: object
      properties:
        currency:
          type: string
          description: The payout currency. EUR and USD are supported.
        type:
          type: string
          description: 'The account type from the requirements: `iban`, `sort_code`, `aba`.'
        accountHolderName:
          type: string
          description: The name on the bank account, as the bank holds it. A clear mismatch is saved but not paid.
        legalType:
          type: string
          enum:
          - PRIVATE
          - BUSINESS
        details:
          type: object
          additionalProperties: true
          description: 'The fields the requirements asked for, for example `{ "IBAN": "DE89…" }`. Never stored: we keep the last four characters and a hash.'
      required:
      - currency
      - type
      - accountHolderName
      - legalType
      - details
    Error:
      type: object
      description: Every non-2xx response is JSON in this shape. Every response (success or error) also carries an `x-request-id` response header; send that header on your request to have your own id echoed back, otherwise the server mints one. On errors the same id is repeated in the `requestId` body field.
      properties:
        statusCode:
          type: integer
          description: Same as the HTTP status code.
        code:
          type: string
          description: 'Present on some refusals: a stable machine-readable reason, e.g. `live_key_required`.'
        message:
          description: Human-readable. A validation failure (400) returns an array of per-field messages instead of one string.
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        errors:
          type: array
          description: 'Present on 400 validation failures: one entry per invalid field. The flat human-readable strings stay in `message` for back-compat; this is the machine-readable, per-field view.'
          items:
            type: object
            properties:
              field:
                type: string
                description: Name of the invalid field, dot-notated for nested properties (e.g. `checkoutFields.0.type`).
              message:
                type: string
                description: Validation messages for that field, joined with `, `.
            required:
            - field
            - message
        requestId:
          type: string
          description: Correlation id, identical to the `x-request-id` response header. Include it when contacting support. On success it is available on the header only, not the body.
        timestamp:
          type: string
          format: date-time
      required:
      - statusCode
      - message
      - timestamp
    BankAccount:
      type: object
      description: 'A bank account as we keep it: a thin reference. The account number itself stays with our bank partner.'
      properties:
        id:
          type: string
          format: uuid
        currency:
          type: string
          description: Upper-case, `EUR` or `USD`.
        account_type:
          type: string
          description: 'The corridor: `iban`, `sort_code`, `aba`.'
        account_identifier_last4:
          type: string
          description: The last four characters of the account number.
        account_holder_name:
          type: string
        legal_type:
          type: string
          enum:
          - PRIVATE
          - BUSINESS
        name_match_status:
          type: string
          enum:
          - success
          - partial
          - failed
          - unknown
          description: How the holder name compared with the name the bank holds, where the bank offers that check (not for every currency). `failed` is never paid; `partial` and `unknown` are paid.
        active:
          type: boolean
        payable:
          type: boolean
          description: 'Can the next payout go to this account right now: active, and the name check did not fail.'
        payableReason:
          type:
          - string
          - 'null'
          description: 'When `payable` is false: why, in a sentence for the merchant.'
      required:
      - id
      - currency
      - account_type
      - account_identifier_last4
      - account_holder_name
      - legal_type
      - name_match_status
      - active
      - payable
      - payableReason
  responses:
    Unauthorized:
      description: Missing or invalid `x-api-key`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            message: Invalid API key
            timestamp: '2026-08-06T12:00:00.000Z'
    NotYourBusiness:
      description: The key does not manage the business named in `AgentaOS-Account`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            message: You cannot act as this business.
    BankAccountsForbidden:
      description: A test key (`live_key_required`); a business you do not manage (`You cannot act as this business.`); or, for a platform key, bank accounts by API not opened for your platform (`bank_accounts_by_api_closed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            message: Bank accounts by API are not enabled for your platform. Ask us to open it, or add the account from the dashboard.
            code: bank_accounts_by_api_closed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Your secret key, from app.agentaos.ai -> Settings -> Developers -> API Keys. The key''s prefix is both its identity and its environment: `sk_test_...` (sandbox, free, no verification) or `sk_live_...` (real money, requires business verification). A missing or invalid key returns 401.'
x-refined-from:
- agentaos-ai-openapi.json
- openapi.json