Retirement accounts

Retirement accounts are tax advantaged brokerage accounts offered exclusively to US taxpayers each carrying their own limitations and taxing qualifications. Today, DriveWealth supports two types of tax advantaged accounts:

Traditional IRAs — deposits are tax deductible
Roth IRAs — deposits are not tax deductible, but assets can grow tax-free and are taxed on withdrawal

🚧
DriveWealth currently supports the ability to trade in equities, fixed income and mutual funds within retirement accounts.

To open a retirement account, the customer must meet the following criteria:

Age 18 or older
A U.S. taxpayer
Provide a valid SSN

Once these steps are completed, opening an Account looks identical to any non-tax-advantaged Account, just with a new management type.

POST /back-office/accounts

{
 "userID": "cc07f91b-7ee1-4868-b8fc-823c70a1b932",
 "accountType": "LIVE",
 "accountManagementType": "RETIREMENT_ROTH_SELF",
 "tradingType": "CASH"
}

Assigning beneficiaries

Utilize the User Beneficiaries endpoint to assign beneficiaries to a retirement account. Please refer to Create Beneficiaries API for request and response details.

Contributions and Distributions

Due to the tax benefits associated with retirement accounts, there are additional requirements to properly identify contributions (money in to) and distributions (money out from) a retirement account. DriveWealth has simplified the selections available for contribution or distribution from a retirement account. A transaction selection is either RETIREMENT_CONTRIBUTION or RETIREMENT_DISTRIBUTION. DriveWealth currently supports monetary contributions and distributions at this time.

Contributions

While making deposits to a customer’s retirement account, DriveWealth provides the ability to properly classify the contribution in line with federal tax reporting. The iraContribution object is provided and includes the list of enumerations that can be provided. A selection of an iraContribution type is required for all retirement account contributions.

In instances where the iraContribution type is either a POSTPONED_CONTRIBUTION or a REPAYMENT, an iraContributionSubType is required.

Refer: Deposit ENUMs for a comprehensive list of all Contribution and Sub-contribution types

Contribution API request and response

POST back-office/funding/deposits
{
    "accountNo": "DWJY000118",
    "amount": 200,
    "currency": "USD",
    "bankAccountID": "bank_152579f3-9787-45d9-a730-047de1bb07c4",
    "iraContribution": "POSTPONED_CONTRIBUTION", 
    "iraContributionSubType": "SC",
    "type": "ACH",
    "note": "Here's some money"
}

{
    "id": "DWJY000118-1758686781303-DVEQJ",
    "accountNo": "DWJY000118",
    "category": "DEPOSIT",
    "currency": "USD",
    "amount": 200,
    "status": {
        "id": 1,
        "message": "Pending",
        "updated": "2025-09-24T04:06:21.303Z"
    },
    "source": {
        "id": "ACH",
        "brand": "ACH",
        "meta_info": "Here's some money|Karthick's spending account|****2971"
    },
    "created": "2025-09-24T04:06:21.303Z",
    "iraContribution": "POSTPONED_CONTRIBUTION",
    "iraContributionSubType": "SC",
    "accountID": "527e55a5-2d67-4854-bdec-4b7b47e2c6ad.1758619903960",
    "userID": "527e55a5-2d67-4854-bdec-4b7b47e2c6ad",
    "transactionCode": "RETIREMENT_CONTRIBUTION",
    "wlpFinTranTypeID": "4df8c5df-7b5c-4a62-b564-6885a20d853b",
    "batch": true,
    "account_number": "DWJY000118"
}

DriveWealth will also require the completion and recording of a form for the following asset movement types:

Direct Rollovers or Indirect Rollovers via form “Retirement Rollover Request Form”.
Internal Transfer, Recharacterization, or Roth Conversion via form “IRA Internal Asset Movement Request Form”.
Inherited IRA, Alternate Payee Payments, or Asset Transfers to another institution via form “IRA Distribution & External Movement Request Form”.

Distributions

All retirement account disbursement requests are facilitated through the withdrawal API. Like contributions, disbursements require additional information for tax reporting and the appropriate handling of tax withholding. The iraDistribution object includes the list of enumerations that can be provided. A selection of an iraDistribution type is required for all retirement account contributions.

In instances where the iraDistribution type is EARLY_DISTRIBUTION_PENALTY_EXCEPTION an iraDistributionSubType is required.

Refer: Redemption ENUMs for a comprehensive list of all Distribution and Sub-distribution types

Distribution request and response

POST back-office/funding/redemptions
{
    "accountNo": "FAGX000996",
    "amount": 10,
    "type": "ACH",
    "bankAccountID": "bank_5dcfe4a1-2536-4496-a87a-c461bedbb783",
    "iraDistribution": "NORMAL_DISTRIBUTION",
    "iraTaxWithholdings": {
        "federalTaxPercentage": 0.5,
        "stateTaxPercentage": 0.5
    },
    "note": "I need some funds pls kbye"
}

{
    "id": "FAGX000996-1758687628755-RDZ4Y",
    "accountNo": "FAGX000996",
    "category": "REDEMPTION",
    "currency": "USD",
    "amount": -10,
    "status": {
        "id": 14,
        "message": "Approved",
        "updated": "2025-09-24T04:20:28.755Z"
    },
    "source": {
        "id": "ACH",
        "meta_info": "I need some funds pls kbye|FAGX000996's Virtual Account|****2035"
    },
    "paymentRef": "FAGX000996-1758687628755-RDZ4Y",
    "created": "2025-09-24T04:20:28.755Z",
    "iraDistribution": "NORMAL_DISTRIBUTION",
    "accountID": "19b75b9e-2528-448c-b3f6-e2b2361c4ee9.1755186779936",
    "userID": "19b75b9e-2528-448c-b3f6-e2b2361c4ee9",
    "transactionCode": "RETIREMENT_DISTRIBUTION",
    "wlpFinTranTypeID": "862732fa-42f2-45a1-acbc-bdc48ff56e10",
    "batch": true,
    "account_number": "FAGX000996"
}

Tax withholding

For distributions from a retirement account, there are also tax withholding requirements. At a federal level, the IRS requires a 10% withholding rate by default. Depending on the state of residency on record for the customer at time of withdrawal, state withholding may also be required by default.

Federal tax

Through the withdrawal API, the customer provides a federal tax withholding election. By default, this withholding rate is set to 10% in accordance with the requirements set by the IRS. The customer may elect to withhold the default rate of 10% or change this withholding amount to a rate of their preference including not withholding at all (0%). DriveWealth will withhold the elected amount (deducted from the distribution amount) and remit payment to the IRS. The withholding amounts will be reported to the IRS and electronically to the customer through Forms 1099R and 5420. Typically, the Forms become available in late February for the relevant tax year. For non-qualified disbursements, it is the customer's responsibility to file and pay the correct taxes and penalties to the IRS.

State tax

DriveWealth will provide the ability to withhold state tax based on each individual state’s tax withholding rules. State withholding falls within one of four categories:

Mandatory: irrespective of federal withholding is applied, the state requires a default withholding rate. This rate can be changed by the customer.
Conditional Mandatory: when federal withholding is applied, the state withholding default rate is applied. This rate can be changed by the customer.
Voluntary: the election to withhold for state tax purposes is solely at the discretion of the customer. By default, the state withholding rate is set to 0%
Not allowed: in select states, withholding is neither allowed nor is the customer able to elect withholding of monies for state tax purposes.

For monies that are withheld, DriveWealth will remit the monies to the state taxation body on the remittance schedule defined by each state. If the customer elects to not withhold taxes, zero state tax withholding will be reported. It is the Customer's responsibility to file and pay the correct state taxes to their state taxation body.

"iraTaxWithHoldings": {
   "type": "object",
   "properties": {
       "federalTaxPercentage": {
           "type": "number",
           "example": 0.1,
           "description": "The percentage amount that should be withheld for federal taxes."
       },
       "stateTaxPercentage": {
           "type": "number",
           "example": 0.1,
           "description": "The percentage amount that should be withheld for state taxes."
       }
   }
}

Reference: Warnings

Contribution warnings

When a user uses invalid reason code for the contribution category:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Invalid iraContributionSubType DD for iraContributionType POSTPONED_CONTRIBUTION. Allowed values: [SC, PO, FD, EO, PL]
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Invalid iraContributionSubType PO for iraContributionType REPAYMENT. Allowed values: [QR, DD, BA, EP, DA, TI]
When a user is missing reason code:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: iraContributionSubType is required for iraContributionType POSTPONED_CONTRIBUTION
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: iraContributionSubType is required for iraContributionType REPAYMENT
When a user provides reason code for the category where code is not required:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: iraContributionSubType must be null for iraContributionType CURRENT_YEAR, DIRECT_ROLLOVER, INDIRECT_ROLLOVER, DIRECT_TRANSFER, CONVERSION, RECHARACTERIZATION
When a user attempts to make a PRIOR_YEAR contribution outside the allowed contribution window of January 1 to April 15 of the current year.
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Prior year contributions can only be made between January 1 and April 15

Distribution warnings

When a user creates distribution with category and with reason code that is not required for the distribution type:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: iraDistributionSubType must be null for iraDistributionType NORMAL_DISTRIBUTION, EARLY_DISTRIBUTION, DIRECT_ROLLOVER, DIRECT_TRANSFER, CONVERSION, RECHARACTERIZATION, REQUIRED_MINIMUM_DISTRIBUTION, RETURN_OF_EXCESS_CONTRIBUTION , QUALIFIED_CHARITABLE_CONTRIBUTION
When a user creates distribution without distribution category:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Missing required field: iraDistribution, for account management type
When a user creates distribute funds from the retirement account with category EARLY_DISTRIBUTION_PENALTY_EXCEPTION and without a reason code:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Missing required field: iraDistributionSubType, for iraDistributionType EARLY_DISTRIBUTION_PENALTY_EXCEPTION
When a user attempts to distribute funds from the retirement account with only iraDistributionSubType
- Invalid or missing parameters in the request body. Refer to the API documentation for details.
When a user attempts to withhold state taxes in a state that does not permit withholding
- Invalid requested amount for state withholding as the state of residence does not allow withholding. The following states do not allow withholding as of January 1, 2025: Alaska, Arizona, Florida, Nevada, New Hampshire, South Dakota, Tennessee, Texas, Washington, Wyoming
When a user attempts to withdrawal an amount inclusive of withholding and fees that exceed cash available for withdrawal:
- Invalid requested amount as the amount exceeds cash available for withdrawal. CAFW must be greater or equal to the sum of withdrawal amount + federal withholding + state withholding (if applicable) + processing fee (if applicable)
When a user attempts to withhold state taxes below the minimum required in mandatory withholding states:
- Invalid requested amount for state withholding. The requested amount is below the state’s mandatory minimum withholding requirement. The following states require a minimum withholding amount as of January 1, 2025: Arkansas, Michigan, Minnesota, Oregon, Virginia.
When a user specifies federal withholding, lives in a state where withholding is required if federal withholding is applied, and attempts to enter a state withholding amount below the state withholding minimum:
- Invalid state withholding percentage. In conditional mandatory withholding states, if federal withholding is requested, the state withholding percentage cannot be less than the state's default rate. The following states enforce this rule as of January 1, 2026: Delaware, Iowa, Kansas, Massachusetts, Maine, North Carolina, Nebraska, Oklahoma, Vermont, California.
When a user attempts a withdrawal when entering a negative value for federal and/or state withholding percentage:
- Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Federal or state percentage should not be negative.