Augustus Accounts API

openapi: 3.2.0
info:
  title: Augustus Banking Accounts API
  description: Augustus Banking API
  version: 0.1.0
  contact:
    name: Augustus
    url: https://docs.augustus.com
    email: developer@augustus.com
servers:
- url: https://api.augustus.com
  description: Production
- url: https://api.sandbox.augustus.com
  description: Sandbox
security:
- BearerAuth: []
tags:
- name: Accounts
paths:
  /v1/accounts:
    get:
      description: Returns a paginated list of accounts.
      operationId: AccountsController_list
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of results per page (1-100). Defaults to 10.
        schema:
          minimum: 1
          maximum: 100
          default: 10
          type: integer
      - name: cursor
        required: false
        in: query
        description: Opaque cursor from a previous next_cursor.
        schema:
          type: string
      - name: account_number
        required: false
        in: query
        description: Filter by exact fiat account number.
        schema:
          minLength: 1
          type: string
      - name: account_holder_name
        required: false
        in: query
        description: Filter by account holder name (case-insensitive phrase match).
        schema:
          minLength: 1
          type: string
      - name: status
        required: false
        in: query
        description: Filter by account status.
        schema:
          type: string
          enum:
          - pending
          - active
          - frozen
      - name: account_program_id
        required: true
        in: query
        description: ID of the account program to list accounts for.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440002
          type: string
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAccountsResponseDto'
      summary: List accounts
      tags:
      - Accounts
    post:
      description: Creates a new account.
      operationId: AccountsController_create
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Account parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountBodyDto'
      responses:
        '200':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResourceDto'
      summary: Create account
      tags:
      - Accounts
  /v1/accounts/{id}:
    get:
      description: Retrieves an account by ID.
      operationId: AccountsController_retrieve
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the account.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
      responses:
        '200':
          description: The account resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResourceDto'
      summary: Retrieve account
      tags:
      - Accounts
  /v1/accounts/{id}/balance:
    get:
      description: Retrieves the available balance for an account.
      operationId: AccountsController_balance
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the account.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
      - name: as_of
        required: false
        in: query
        description: ISO 8601 UTC timestamp to retrieve balance at. Must be at least 5 minutes in the past.
        schema:
          format: date-time
          example: '2026-01-15T10:40:00Z'
          type: string
      responses:
        '200':
          description: The account balance resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceResourceDto'
      summary: Retrieve account balance
      tags:
      - Accounts
  /v1/accounts/{id}/freeze:
    post:
      description: Freezes an account
      operationId: AccountsController_freeze
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the account.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account frozen successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResourceDto'
      summary: Freeze account
      tags:
      - Accounts
  /v1/accounts/{id}/close:
    post:
      description: Closes an account
      operationId: AccountsController_close
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the account.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Close account parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseAccountBodyDto'
      responses:
        '200':
          description: Account closed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResourceDto'
      summary: Close account
      tags:
      - Accounts
  /v1/accounts/{id}/unfreeze:
    post:
      description: Unfreezes an account
      operationId: AccountsController_unfreeze
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the account.
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440001
          type: string
      - name: Idempotency-Key
        in: header
        description: Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account unfrozen successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResourceDto'
      summary: Unfreeze account
      tags:
      - Accounts
components:
  schemas:
    ListAccountsResponseDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique identifier of the account.
                example: 550e8400-e29b-41d4-a716-446655440001
              type:
                type: string
                description: Resource type discriminator.
                enum:
                - account
              currency:
                type: string
                enum:
                - EUR
                - GBP
                - USD
                - USDC
                description: Currency code (ISO 4217 or crypto).
                example: USD
              status:
                type: string
                enum:
                - pending
                - active
                - frozen
                - closed
                description: Current status of the account.
                example: active
              asset_type:
                type: string
                enum:
                - fiat
                - crypto
                description: Asset type of the account.
              label:
                type: string
                description: Human-readable label for the account.
                example: Operating USD account
              financial_addresses:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/AbaFinancialAddress'
                  - $ref: '#/components/schemas/IbanFinancialAddress'
                  - $ref: '#/components/schemas/SortCodeFinancialAddress'
                  - $ref: '#/components/schemas/BicFinancialAddress'
                  - $ref: '#/components/schemas/CryptoWalletFinancialAddress'
                description: Payment identifiers (e.g. IBAN, account number, wallet address) through which this account can send or receive funds.
              created_at:
                type: string
                format: date-time
                description: ISO 8601 UTC timestamp when the account was created.
                example: '2026-01-15T10:30:00Z'
              updated_at:
                type: string
                format: date-time
                description: ISO 8601 UTC timestamp when the account was last updated.
                example: '2026-01-15T10:35:00Z'
              metadata:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 500
                description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
                example:
                  invoice_id: INV-2026-0042
            required:
            - id
            - type
            - currency
            - status
            - asset_type
            - label
            - financial_addresses
            - created_at
            - updated_at
            - metadata
            additionalProperties: false
        has_more:
          type: boolean
        next_cursor:
          type: string
          example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
          nullable: true
        has_previous:
          type: boolean
        previous_cursor:
          type: string
          example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
          nullable: true
      required:
      - data
      - has_more
      - next_cursor
      - has_previous
      - previous_cursor
      additionalProperties: false
    SortCodeFinancialAddress:
      type: object
      properties:
        type:
          type: string
          description: Discriminator for UK sort code financial address.
          enum:
          - sort_code
        sort_code:
          type: string
          description: UK sort code (6 digits).
        account_number:
          type: string
          description: UK account number (8 digits).
        account_holder_name:
          type: string
          description: Name of the account holder.
      required:
      - type
      - sort_code
      - account_number
      - account_holder_name
      additionalProperties: false
      title: UK Sort Code
      example:
        type: sort_code
        sort_code: '040075'
        account_number: '37778842'
        account_holder_name: Acme Sandbox Ltd.
    CryptoWalletFinancialAddress:
      type: object
      properties:
        type:
          type: string
          description: Discriminator for crypto wallet financial address.
          enum:
          - crypto_wallet
        address:
          type: string
          description: Wallet address on the specified blockchain.
        blockchain:
          type: string
          enum:
          - bitcoin
          - ethereum
          - solana
          - polygon
          - bitcoin_testnet4
          - ethereum_sepolia
          - solana_devnet
          - polygon_amoy
          description: Blockchain network for the crypto wallet.
          example: ethereum_sepolia
      required:
      - type
      - address
      - blockchain
      additionalProperties: false
      title: Wallet
      example:
        type: crypto_wallet
        address: '0x1111111111111111111111111111111111111111'
        blockchain: ethereum_sepolia
    AbaFinancialAddress:
      type: object
      properties:
        type:
          type: string
          description: Discriminator for ABA wire financial address.
          enum:
          - aba
        routing_number:
          type: string
          description: ABA routing number (9 digits).
        account_number:
          type: string
          description: Bank account number.
        account_holder_name:
          type: string
          description: Name of the account holder.
        account_type:
          type: string
          enum:
          - checking
          - savings
          - null
          description: Whether the account is a checking or a savings account, or null if not provided.
          nullable: true
      required:
      - type
      - routing_number
      - account_number
      - account_holder_name
      - account_type
      additionalProperties: false
      title: ABA
      example:
        type: aba
        routing_number: '110000000'
        account_number: 000123456789
        account_holder_name: Acme Sandbox Ltd.
        account_type: checking
    AccountResourceDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the account.
          example: 550e8400-e29b-41d4-a716-446655440001
        type:
          type: string
          description: Resource type discriminator.
          enum:
          - account
        currency:
          type: string
          enum:
          - EUR
          - GBP
          - USD
          - USDC
          description: Currency code (ISO 4217 or crypto).
          example: USD
        status:
          type: string
          enum:
          - pending
          - active
          - frozen
          - closed
          description: Current status of the account.
          example: active
        asset_type:
          type: string
          enum:
          - fiat
          - crypto
          description: Asset type of the account.
        label:
          type: string
          description: Human-readable label for the account.
          example: Operating USD account
        financial_addresses:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/AbaFinancialAddress'
            - $ref: '#/components/schemas/IbanFinancialAddress'
            - $ref: '#/components/schemas/SortCodeFinancialAddress'
            - $ref: '#/components/schemas/BicFinancialAddress'
            - $ref: '#/components/schemas/CryptoWalletFinancialAddress'
          description: Payment identifiers (e.g. IBAN, account number, wallet address) through which this account can send or receive funds.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the account was created.
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the account was last updated.
          example: '2026-01-15T10:35:00Z'
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 500
          description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
          example:
            invoice_id: INV-2026-0042
      required:
      - id
      - type
      - currency
      - status
      - asset_type
      - label
      - financial_addresses
      - created_at
      - updated_at
      - metadata
      additionalProperties: false
    BicFinancialAddress:
      type: object
      properties:
        type:
          type: string
          description: Discriminator for BIC + local account financial address.
          enum:
          - bic
        bic:
          type: string
          description: ISO 9362 Bank Identifier Code (8 or 11 characters).
        account_number:
          type: string
          description: Local-format bank account number.
        account_holder_name:
          type: string
          description: Name of the account holder.
        local_bank_code:
          type: string
          description: Domestic bank or branch code where the destination country uses one (for example the BSB in Australia), or null.
          nullable: true
        account_type:
          type: string
          enum:
          - checking
          - savings
          - null
          description: Whether the account is a checking or a savings account, or null if not provided.
          nullable: true
      required:
      - type
      - bic
      - account_number
      - account_holder_name
      - local_bank_code
      - account_type
      additionalProperties: false
      title: BIC
      example:
        type: bic
        bic: ANZBAU3MXXX
        account_number: '123456789'
        account_holder_name: Acme Sandbox Pty Ltd.
        local_bank_code: '012003'
        account_type: checking
    IbanFinancialAddress:
      type: object
      properties:
        type:
          type: string
          description: Discriminator for IBAN financial address.
          enum:
          - iban
        iban:
          type: string
          description: International Bank Account Number.
        account_holder_name:
          type: string
          description: Name of the account holder.
        bic:
          type: string
          description: Bank Identifier Code, or null if not provided.
          nullable: true
        account_type:
          type: string
          enum:
          - checking
          - savings
          - null
          description: Whether the account is a checking or a savings account, or null if not provided.
          nullable: true
      required:
      - type
      - iban
      - account_holder_name
      - bic
      - account_type
      additionalProperties: false
      title: IBAN
      example:
        type: iban
        iban: DE89370400440532013000
        account_holder_name: Acme Sandbox Ltd.
        bic: COBADEFFXXX
        account_type: checking
    AccountBalanceResourceDto:
      type: object
      properties:
        type:
          type: string
          description: Resource type discriminator.
          enum:
          - account_balance
        account_id:
          type: string
          format: uuid
          description: Unique identifier of the account.
          example: 550e8400-e29b-41d4-a716-446655440001
        amount:
          type: object
          properties:
            available:
              type: string
              description: Available balance as a string decimal (e.g. "100.50").
              example: '100.50'
            pending:
              type: string
              description: Pending balance as a string decimal (e.g. "7.50").
              example: '100.50'
          required:
          - available
          - pending
          additionalProperties: false
        currency:
          type: string
          enum:
          - EUR
          - GBP
          - USD
          - USDC
          description: Currency code (ISO 4217 or crypto).
          example: USD
        as_of:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the balance was retrieved.
          example: '2026-01-15T10:40:00Z'
      required:
      - type
      - account_id
      - amount
      - currency
      - as_of
      additionalProperties: false
    CloseAccountBodyDto:
      type: object
      properties:
        reason:
          type: string
          enum:
          - aml_risk_fraud
          - client_request
          description: Reason for closing the account.
      required:
      - reason
      additionalProperties: false
    CreateAccountBodyDto:
      type: object
      properties:
        account_program_id:
          type: string
          format: uuid
          description: ID of the account program to create the account under.
          example: 550e8400-e29b-41d4-a716-446655440002
        account_holder_id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: ID of an existing account holder to provision the account for.
          example: 68e0a1b2c3d4e5f60718293a
        metadata:
          type: object
          propertyNames:
            type: string
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
          description: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
          example:
            invoice_id: INV-2026-0042
          nullable: true
      required:
      - account_program_id
      - account_holder_id
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Bearer token for authentication with Augustus Banking API
x-provenance:
  method: harvested
  publisher: Augustus
  source: https://api.augustus.com/openapi/2026-05-01.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)