MethodFi Accounts API

openapi: 3.2.0
info:
  title: Methodfi Accounts API
  version: '1.0'
  description: 'Operations tagged Accounts across 2 of this provider''s published API definitions: methodfi-openapi-original.yml, methodfi-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://production.methodfi.com
  description: Production
- url: https://sandbox.methodfi.com
  description: Sandbox
- url: https://dev.methodfi.com
  description: Development
tags:
- name: Accounts
  description: Financial accounts (ACH, liability, clearing, debit card)
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: List all accounts
      description: Returns a paginated list of accounts. Results can be filtered by status, type, holder, and date range.
      tags:
      - Accounts
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageLimitParam'
      - $ref: '#/components/parameters/PageCursorParam'
      - $ref: '#/components/parameters/FromDateParam'
      - $ref: '#/components/parameters/ToDateParam'
      - name: status
        in: query
        required: false
        description: Filter accounts by status.
        schema:
          type: string
          enum:
          - active
          - disabled
      - name: type
        in: query
        required: false
        description: Filter accounts by type.
        schema:
          type: string
          enum:
          - ach
          - liability
          - clearing
          - debit_card
      - name: consent_status
        in: query
        required: false
        description: Filter accounts by consent status.
        schema:
          type: string
          enum:
          - pending
          - withdrawn
          - approved
      - name: holder_id
        in: query
        required: false
        description: Filter accounts by the entity ID that owns them.
        schema:
          type: string
          pattern: ^ent_\w+$
      - name: holder_ids
        in: query
        required: false
        description: Filter accounts by one or more entity IDs.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            pattern: ^ent_\w+$
      - name: include_pending_consent
        in: query
        required: false
        description: Include accounts that are still pending consent.
        schema:
          type: boolean
      - name: liability.mch_id
        in: query
        required: false
        description: Filter liability accounts by merchant ID.
        schema:
          type: string
          pattern: ^mch_\w+$
      - name: liability.type
        in: query
        required: false
        description: Filter liability accounts by liability type.
        schema:
          type: string
          enum:
          - credit_card
          - auto_loan
          - mortgage
          - personal_loan
          - student_loan
          - student_loans
          - collection
          - credit_builder
          - insurance
          - loan
          - medical
          - utility
          - bnpl
          - fintech
      - name: liability.ownership
        in: query
        required: false
        description: Filter liability accounts by ownership type.
        schema:
          type: string
          enum:
          - primary
          - authorized
          - joint
          - unknown
      - $ref: '#/components/parameters/expand_accounts'
      responses:
        '200':
          description: A paginated list of accounts.
          headers:
            Pagination-Page:
              $ref: '#/components/headers/Pagination-Page'
            Pagination-Page-Count:
              $ref: '#/components/headers/Pagination-Page-Count'
            Pagination-Page-Limit:
              $ref: '#/components/headers/Pagination-Page-Limit'
            Pagination-Total-Count:
              $ref: '#/components/headers/Pagination-Total-Count'
            Pagination-Page-Cursor-Prev:
              $ref: '#/components/headers/Pagination-Page-Cursor-Prev'
            Pagination-Page-Cursor-Next:
              $ref: '#/components/headers/Pagination-Page-Cursor-Next'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAccount
      summary: Create an account
      description: Creates a new account for the specified entity. The request body must include exactly one of `ach`, `liability`, `clearing`, or `debit_card` to determine the account type.
      tags:
      - Accounts
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreateRequest'
            examples:
              ach:
                summary: Create an ACH account
                value:
                  type: ach
                  holder_id: ent_au22b1fbFJbp8
                  ach:
                    routing: '111000025'
                    number: 000123456789
                    type: checking
                  metadata:
                    customer_reference: acct-001
              liability:
                summary: Create a liability account
                value:
                  type: liability
                  holder_id: ent_au22b1fbFJbp8
                  liability:
                    mch_id: mch_4c1j9e4t4R8Qd
                    account_number: '4111111111111111'
                  metadata:
                    portfolio: cards
              debit_card:
                summary: Create a debit card account
                value:
                  type: debit_card
                  holder_id: ent_au22b1fbFJbp8
                  debit_card:
                    number: '4111111111111111'
                    exp_month: '12'
                    exp_year: 2028
                    cvv: '123'
                    billing_zip_code: '78701'
      responses:
        '200':
          description: The newly created account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
              example:
                success: true
                data:
                  id: acc_b9q2XVAnNFbp3
                  holder_id: ent_au22b1fbFJbp8
                  type: ach
                  status: active
                  consent_status: approved
                  ach:
                    routing: '111000025'
                    number: 000123456789
                    type: checking
                  liability: null
                  clearing: null
                  debit_card: null
                  capabilities: []
                  available_capabilities:
                  - payments:send
                  - payments:receive
                  error: null
                  metadata:
                    customer_reference: acct-001
                  products: []
                  restricted_products: []
                  subscriptions: []
                  available_subscriptions: []
                  restricted_subscriptions: []
                  latest_verification_session: null
                  balance: null
                  payoff: null
                  payment_instrument: null
                  card_brand: null
                  update: null
                  attribute: null
                  sensitive: null
                  created_at: '2026-01-15T18:30:00.000Z'
                  updated_at: '2026-01-15T18:30:00.000Z'
                message: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development
  /accounts/{accountId}:
    get:
      operationId: retrieveAccount
      summary: Retrieve an account
      description: Retrieves an account by its unique identifier.
      tags:
      - Accounts
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/expand_accounts'
      responses:
        '200':
          description: The requested account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateAccount
      summary: Update an account
      description: Updates an account's metadata or liability account number.
      tags:
      - Accounts
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdateRequest'
            examples:
              metadata:
                summary: Update account metadata
                value:
                  metadata:
                    servicing_tier: gold
              liability:
                summary: Update a liability account number
                value:
                  liability:
                    credit_card:
                      number: '5555444433331111'
      responses:
        '200':
          description: Account updated successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: 'null'
                    example: null
                  message:
                    type:
                    - 'null'
                    - string
                    example: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development
  /accounts/{acc_id}:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getAccount
      tags:
      - Accounts
      summary: Retrieve an account
      responses:
        '200':
          description: The account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse_2'
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
  /accounts/{acc_id}/balances:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getAccountBalance
      tags:
      - Accounts
      summary: Retrieve the latest balance
      description: Retrieves the real-time balance from the account's financial institution.
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
  /accounts/{acc_id}/payoff:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getAccountPayoff
      tags:
      - Accounts
      summary: Retrieve a payoff
      responses:
        '200':
          description: Payoff
          content:
            application/json:
              schema:
                type: object
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
  /accounts/{acc_id}/verification_sessions:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    post:
      operationId: createAccountVerificationSession
      tags:
      - Accounts
      summary: Create an account verification session
      description: Verify an account via micro-deposits, instant network, or a supported aggregator (Plaid, MX, Teller).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Verification session
          content:
            application/json:
              schema:
                type: object
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
components:
  parameters:
    AccountIdParam:
      name: accountId
      in: path
      required: true
      description: Unique identifier for the account.
      schema:
        type: string
        pattern: ^acc_\w+$
    PageLimitParam:
      name: page_limit
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    ToDateParam:
      name: to_date
      in: query
      required: false
      description: Filter results to this date (inclusive, YYYY-MM-DD format).
      schema:
        type: string
        format: date
    PageCursorParam:
      name: page_cursor
      in: query
      required: false
      description: Cursor for cursor-based pagination. Use the value from `Pagination-Page-Cursor-Next` or `Pagination-Page-Cursor-Prev` response headers.
      schema:
        type: string
    idempotency_key:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Idempotency key for safely retrying a write request. Reuse the same value when

        retrying the same logical operation to avoid creating duplicate side effects.

        '
      schema:
        type: string
        format: uuid
    method_version:
      name: Method-Version
      in: header
      required: true
      description: 'API version to use for this request. This spec targets `2025-12-01`.

        The SDK sets this header automatically.

        '
      schema:
        type: string
        enum:
        - '2025-12-01'
        default: '2025-12-01'
    expand_accounts:
      name: expand
      in: query
      required: false
      description: 'Expand related account resources inline. Supports the account expandable fields

        documented by the API validator for account list and retrieve operations.

        '
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
          - sensitive
          - balance
          - card_brand
          - attribute
          - payoff
          - transaction
          - update
          - payment_instrument
          - latest_verification_session
          - liability.mch_id
    FromDateParam:
      name: from_date
      in: query
      required: false
      description: Filter results from this date (inclusive, YYYY-MM-DD format).
      schema:
        type: string
        format: date
    PageParam:
      name: page
      in: query
      required: false
      description: Page number for pagination (1-indexed).
      schema:
        type: integer
        minimum: 1
        default: 1
    PageLimit:
      name: page_limit
      in: query
      required: false
      schema:
        type: integer
        default: 50
        maximum: 100
    AccountId:
      name: acc_id
      in: path
      required: true
      schema:
        type: string
      description: The account identifier (e.g. acc_xxx).
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
  schemas:
    AccountCreateRequest:
      description: 'Request body for creating an account.

        `type` is recommended and used for discrimination in generated clients, but

        the API can also infer the account type from the nested object you provide.

        '
      oneOf:
      - $ref: '#/components/schemas/CreateAchAccountRequest'
      - $ref: '#/components/schemas/CreateLiabilityAccountRequest'
      - $ref: '#/components/schemas/CreateClearingAccountRequest'
      - $ref: '#/components/schemas/CreateDebitCardAccountRequest'
      discriminator:
        propertyName: type
        mapping:
          ach: '#/components/schemas/CreateAchAccountRequest'
          liability: '#/components/schemas/CreateLiabilityAccountRequest'
          clearing: '#/components/schemas/CreateClearingAccountRequest'
          debit_card: '#/components/schemas/CreateDebitCardAccountRequest'
    AccountDebitCard:
      type:
      - object
      - 'null'
      description: Debit card account details. Present when `type` is `debit_card`.
      properties:
        network:
          type: string
          description: The card network.
        mask:
          type: string
          description: Last 4 digits of the card number.
        issuer:
          type: string
          description: The card issuer.
    CreateClearingAccountRequest:
      type: object
      description: Create a clearing account.
      required:
      - holder_id
      - clearing
      properties:
        type:
          type: string
          enum:
          - clearing
        holder_id:
          type: string
          description: The entity ID that will own this account.
          pattern: ^ent_\w+$
        clearing:
          type: object
          description: Clearing account details.
          required:
          - type
          properties:
            type:
              type: string
              description: The type of clearing account to create.
              enum:
              - single_use
              - multi_use
        metadata:
          $ref: '#/components/schemas/Metadata'
    ErrorEnvelope:
      type: object
      required:
      - success
      - data
      - message
      properties:
        success:
          type: boolean
          description: Always `false` for error responses.
        data:
          type: object
          required:
          - error
          properties:
            error:
              $ref: '#/components/schemas/ErrorObject'
        message:
          type: string
    CreateLiabilityAccountRequest:
      type: object
      description: Create a liability account.
      required:
      - holder_id
      - liability
      properties:
        type:
          type: string
          enum:
          - liability
        holder_id:
          type: string
          description: The entity ID that will own this account.
          pattern: ^ent_\w+$
        liability:
          type: object
          description: Liability account details.
          properties:
            mch_id:
              type: string
              description: The merchant ID for the liability.
              pattern: ^mch_\w+$
            account_number:
              type: string
              description: Full account number for the liability.
            number:
              type: string
              description: Alternative liability account number field.
            credit_card:
              type: object
              description: Optional supplemental card details for liability accounts.
              required:
              - exp_month
              - exp_year
              properties:
                billing_zip_code:
                  type: string
                cvv:
                  type: string
                exp_month:
                  type: string
                  pattern: ^(0[1-9]|1[0-2])$
                exp_year:
                  type: integer
          oneOf:
          - required:
            - account_number
          - required:
            - number
        metadata:
          $ref: '#/components/schemas/Metadata'
    ResourceError:
      type:
      - object
      - 'null'
      required:
      - type
      - code
      - message
      properties:
        type:
          type: string
        code:
          type: integer
        sub_type:
          type:
          - string
          - 'null'
        message:
          type: string
    ListEnvelope:
      type: object
      description: Standard envelope for successful responses that return a list payload.
      required:
      - success
      - data
      - message
      properties:
        success:
          type: boolean
          description: Always `true` for successful responses.
        data:
          description: Operation-specific list payload.
        message:
          type:
          - string
          - 'null'
      example:
        success: true
        data: []
        message: null
    AccountExpandableUpdate:
      title: AccountExpandableUpdate
      description: 'The latest update ID. This field is expandable. When expanded, returns the full AccountUpdate object.

        '
      oneOf:
      - type: string
        pattern: ^upd_\w+$
      - type: 'null'
      - $ref: '#/components/schemas/AccountUpdate'
    AccountAttribute:
      type: object
      description: An attribute record for an account containing financial data attributes.
      required:
      - id
      - account_id
      - status
      - attributes
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the account attribute.
          pattern: ^acc_attr_\w+$
          example: acc_attr_eTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this attribute belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the attribute request.
          enum:
          - completed
          - pending
          - failed
        attributes:
          type: object
          description: Financial data attributes for the account.
          additionalProperties: true
        error:
          $ref: '#/components/schemas/ResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the attribute was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the attribute was last updated.
    MerchantType:
      type: string
      enum:
      - auto_loan
      - bank
      - bnpl
      - business_loan
      - city
      - collection
      - county
      - credit_builder
      - credit_card
      - electric_utility
      - fintech
      - home_equity_loan
      - home_loan
      - insurance
      - internet_utility
      - loan
      - medical
      - mortgage
      - personal_loan
      - student_loan
      - student_loans
      - subscription
      - telephone_utility
      - television_utility
      - unknown
      - utility
      - waste_utility
      - water_utility
    AccountExpandableCardBrand:
      title: AccountExpandableCardBrand
      description: 'The latest card brand ID. This field is expandable. When expanded, returns the full AccountCardBrand object.

        '
      oneOf:
      - type: string
        pattern: ^cbrd_\w+$
      - type: 'null'
      - $ref: '#/components/schemas/AccountCardBrand'
    AccountClearing:
      type:
      - object
      - 'null'
      description: Clearing account details. Present when `type` is `clearing`.
      properties:
        type:
          type: string
          description: The type of clearing account.
          enum:
          - single_use
          - multi_use
        routing:
          type: string
          description: The clearing routing number.
        number:
          type: string
          description: The clearing account number.
    AccountPaymentInstrument:
      type: object
      description: A payment instrument for an account.
      required:
      - id
      - account_id
      - status
      - type
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the payment instrument.
          pattern: ^pmt_inst_\w+$
          example: pmt_inst_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this payment instrument belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the payment instrument.
          enum:
          - pending
          - in_progress
          - completed
        type:
          type: string
          description: The type of payment instrument.
          enum:
          - card
          - network_token
          - inbound_achwire_payment
        chargeable:
          type: boolean
          description: Whether this payment instrument is currently chargeable.
        card:
          type:
          - object
          - 'null'
          description: Card details. Present when type is card.
          properties:
            number:
              type: string
              description: The card number.
            exp_month:
              type: string
              description: Card expiration month.
            exp_year:
              type: string
              description: Card expiration year.
            billing_zip_code:
              type: string
              description: Billing zip code.
        network_token:
          type:
          - object
          - 'null'
          description: Network token details. Present when type is network_token.
          properties:
            token:
              type: string
              description: The network token value.
        inbound_achwire_payment:
          type:
          - object
          - 'null'
          description: ACH/wire payment details. Present when type is inbound_achwire_payment.
          properties:
            account_number:
              type: string
              description: The account number.
            routing_number:
              type: string
              description: The routing number.
        error:
          $ref: '#/components/schemas/ResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment instrument was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the payment instrument was last updated.
    AccountSensitive:
      type: object
      description: Sensitive data for an account.
      required:
      - id
      - account_id
      - status
      - type
      - fields
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the sensitive record.
          pattern: ^astv_\w+$
          example: astv_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this sensitive data belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the sensitive data request.
          enum:
          - completed
          - pending
          - failed
        type:
          type: string
          description: The type of sensitive data.
        fields:
          type: array
          description: List of sensitive data fields retrieved.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the field.
              value:
                type: string
                description: Value of the field.
        error:
          $ref: '#/components/schemas/AccountSensitiveResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the sensitive record was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the sensitive record was last updated.
    AccountLiability:
      type:
      - object
      - 'null'
      description: Liability account details. Present when `type` is `liability`.
      required:
      - mch_id
      - mask
      - ownership
      - fingerprint
      - type
      - sub_type
      - name
      properties:
        mch_id:
          title: AccountLiabilityExpandableMerchant
          description: The merchant ID associated with this liability.
          oneOf:
          - type: string
            pattern: ^mch_\w+$
          - $ref: '#/components/schemas/Merchant'
        mask:
          type:
          - string
          - 'null'
          description: Last 4 digits of the account number.
          example: '4321'
        ownership:
          type:
          - string
          - 'null'
          description: Ownership type of the account.
          enum:
          - primary
          - authorized
          - joint
          - unknown
          - null
        fingerprint:
          type:
          - string
          - 'null'
          description: Unique fingerprint for de-duplication.
        type:
          type: string
          description: The type of liability.
          enum:
          - credit_card
          - auto_loan
          - mortgage
          - personal_loan
          - student_loan
          - student_loans
          - collection
          - credit_builder
          - insurance
          - loan
          - medical
          - utility
          - bnpl
          - fintech
        sub_type:
          type:
          - string
          - 'null'
          description: More specific classification of the liability type.
        name:
          type:
          - string
          - 'null'
          description: Display name of the liability account.
    AccountCardBrand:
      type: object
      description: Card brand information for an account.
      required:
      - id
      - account_id
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the card brand.
          pattern: ^cbrd_\w+$
          example: cbrd_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this card brand belongs to.
          pattern: ^acc_\w+$
        brands:
          type:
  

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/methodfi/refs/heads/main/openapi/methodfi-accounts-api-openapi.yml