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:

1. Traditional IRAs — contributions may be tax deductible and earnings grow tax deferred
2. Roth IRAs — contributions are not tax deductible and offer tax-free qualified withdrawals in retirement

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

1. Age 18 or older
2. A U.S. taxpayer
3. 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:

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

Contributions Limits & Distributions

DriveWealth validates contribution eligibility and maximum limits for Traditional and Roth IRA accounts in real-time to prevent over-contributions. Traditional and Roth IRAs are subject to a combined annual contribution limit per individual user ID. DriveWealth aggregates posted and pending contributions for the applicable tax year across accounts associated with the same individual user ID within each partner's program independently. DriveWealth does not enforce contribution limits across multiple partners or external providers.

(Note: Catch-up age eligibility is calculated as of December 31st of the target tax year.)

• Tax year determination: The target tax year is derived dynamically based on the transaction date and the contribution type (e.g., CURRENT_YEAR or PRIOR_YEAR). Prior year contributions must be submitted before the federal tax deadline (typically April 15th).
• Multi-year contributions: Between January 1 and the tax deadline, customers may submit contributions for both the prior and current tax years. These are tracked independently against their respective annual limits.
• Catch-up validation: Customers turning 50 or older by December 31st of the target tax year are eligible for an increased catch-up limit.
• Transaction impacts: Direct contributions add to the utilized limit, while return of excess contributions subtract from it. Asset movements such as recharacterizations, rollovers, transfers, and conversions are not classified as new contributions and do not impact the annual limit.

Warnings & Rejections

• When a contribution meets or crosses the annual limit (Approved):
  • If a deposit reaches the exact annual limit, OR if a single deposit pushes the combined total over the limit, the transaction is approved with a standard success message.

    📘 The API will always accept the single contribution that meets or crosses the maximum limit. However, once the limit is met or exceeded, any subsequent contributions will be rejected.

"status": {
    "id": 14,
    "message": "Approved",
    "comment": "Payment successfully submitted. Moved to Approved",
    "updated": "2026-04-29T16:09:30.111Z"
}

• When a user has already met or exceeded their annual limit (including catch-up eligibility) and attempts to submit an additional contribution:
  • The request is rejected entirely with an E032 error code.

{
    "errorCode": "E032",
    "message": "Invalid or missing parameters in the request body. Refer to the API documentation for details. Details: Already contributed amount of $9,000.00 meets or exceeds the annual limit of $7,500.00 for tax year 2026"
}

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.1,
        "stateTaxPercentage": 0.1
    },
    "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 three categories:

1. Conditional Mandatory: when federal withholding is applied, the state withholding default rate is applied. This rate can be changed by the customer.
2. 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%
3. 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

Contribution warnings

1. 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]

2. 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

3. 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

4. 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
5. 
   

Distribution warnings

1. 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
2. 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
3. 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
4. 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.
5. 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.
6. 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)
7. 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: California, Delaware, Iowa, Kansas, Maine, Massachusetts, Nebraska, North Carolina, Oklahoma, Vermont.
8. 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.