---
title: "Add a Bank Account"
method: POST
path: "/v1/users/{userId}/bankAccounts"
tags: ["User Management"]
---

# Add a Bank Account

`POST /v1/users/{userId}/bankAccounts`

## Request

- Base URL: `https://sandbox-api.spinwheel.io`
- URL: `https://sandbox-api.spinwheel.io/v1/users/{userId}/bankAccounts`
- Auth: API key in header `Authorization`

Create a bank account for the user

## Path parameters

- `userId` string, required

## Request body

- CreateBankAccountRequest
  - `routingNumber` string, required: Bank account routing number
  - `accountNumber` string, required: Bank account number
  - `accountType` 'CHECKING' | 'SAVINGS': Bank account type
  - `telephoneBankingPin` string: The telephone banking pin associated with the user's account

## Response `201`

Successful response

- CreateBankAccountResponse
  - `status` ResponseStatus, required
    - `code` number
    - `desc` string
    - `messages` Message[]
      - `desc` string, required
      - `type` 'ERROR' | 'WARN' | 'INFO'
  - `data` CreateBankAccountResponseData, required
    - `bankAccountId` string, required: Id of the created bank account
    - `userId` string, required: The id of the user for which the bank account was created
    - `accountNumberLastFourDigits` string, required: Bank account number's last 4 digits
    - `accountType` 'CHECKING' | 'SAVINGS': Bank account type
    - `createdOn` number, required: Bank account created on timestamp
    - `updatedOn` number, required: Bank account updated on timestamp
    - `capabilities` CapabilityMatrix, required
      - `payments` PaymentsCapability
        - `billPayment` Capability, required
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `pushToCard` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `receiveOnlyPayment` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
      - `data` DataCapability
        - `realtimeBalance` Capability, required
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `payoffSummary` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `liabilityGroupPayoffQuote` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `statementSummary` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `annualPercentageRate` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.
        - `cardBrand` Capability
          - `availability` 'NOT_SUPPORTED' | 'SUPPORTED' | 'FIELD_ERROR', required: The availability status of a capability
          - `fieldErrors` FieldError[]: Field-level errors if applicable.
            - `field` string, required: The field associated with the error.
            - `error` string, required: The reason for the error.
          - `description` 'INSTITUTION_NOT_SUPPORTED' | 'INSTITUTION_DISABLED' | 'REFRESH_EXHAUSTED' | 'NOT_PRIMARY_ACCOUNT_HOLDER' | 'ACCOUNT_TERMINATED' | 'CLOSED_ACCOUNT_NO_BALANCE' | 'CLOSED_ACCOUNT' | 'ACCOUNT_NUMBER_VERIFICATION_FAILED': Description of why the capability is not supported, if applicable.
          - `nextEligibleRefreshOn` number: The earliest timestamp that the capability will be available, if applicable.
          - `liabilityGroupId` string: Unique identifier of the liability group for the capability.

## Other responses

- `400`: Bad Request
- `409`: Conflict

---

[API](https://skmtc.dev/spinwheel/apis/optimize.md) - [All operations](https://skmtc.dev/spinwheel/apis/optimize/llms.txt) - [OpenAPI document](https://skmtc.dev/spinwheel/apis/optimize/revisions/6222309663d2?raw)