Getting Started with IRA Accounts for Broker API
IRA accounts are governed by a complex set of IRS rules and regulations, but Alpaca simplifies this with our Broker API integration. This resource will cover the basics of IRA accounts and show you how to use various Broker API endpoints to start offering IRAs to your customers immediately.
How to Create an IRA Account
The existing account creation request will be used to create an IRA account but with the addition of a few new fields such as the account_type and account_sub_type fields. There will also be some additional onboarding questions that customers must answer to create their IRA account. The full list of new fields supported can be found in our API documentation.
Please reach out to your dedicated Customer Success Manager for the complete onboarding steps you'll need to guide your customers through.
Request
POST /v1/accounts/Sample Request Body
{
"account_type": "ira",
"account_sub_type": "roth",
"enabled_assets": ["us_equity"],
"contact": {
"email_address": "[email protected]",
"phone_number": "555-666-7788",
"street_address": ["20 N San Mateo Dr"],
"unit": "6G",
"city": "San Mateo",
"state": "CA",
"postal_code": "12345"
},
"identity": {
"given_name": "John",
"family_name": "Smith",
"date_of_birth": "1940-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"country_of_citizenship": "USA",
"country_of_tax_residence": "USA",
"funding_source": ["employment_income"],
"annual_income_min": "30000",
"annual_income_max": "50000",
"liquid_net_worth_min": "100000",
"liquid_net_worth_max": "150000",
"marital_status": "MARRIED"
},
"disclosures": {
"is_control_person": false,
"is_affiliated_exchange_or_finra": false,
"is_politically_exposed": false,
"immediate_family_exposed": false,
"employment_status": "retired"
},
"agreements": [
{
"agreement": "customer_agreement",
"signed_at": "2020-09-11T18:13:44Z",
"ip_address": "185.13.21.99",
"revision": "19.2022.02"
}
],
"beneficiaries": [
{
"given_name": "Jane",
"middle_name": "middle",
"family_name": "Smith",
"date_of_birth": "1940-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"relationship": "spouse",
"type": "primary",
"share_pct": "33.34"
},
{
"given_name": "John",
"family_name": "Smith",
"date_of_birth": "2000-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"relationship": "other",
"type": "primary",
"share_pct": "33.33"
},
{
"given_name": "Sally",
"family_name": "Smith",
"date_of_birth": "2000-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"relationship": "other",
"type": "primary",
"share_pct": "33.33"
}
]
}
Response
The existing account model returned when creating a new account will continue to be used.
How to Manage Beneficiaries
Beneficiaries are especially important for IRA accounts since they are meant to be used to generate savings over a long period of time. However, to ensure a smooth onboarding experience, specifying beneficiaries at the time of account opening is not required. Beneficiaries can be set or updated anytime after account creation. This function would be managed via the existing account update endpoint.
Important note: updating beneficiaries via this endpoint will replace all existing beneficiaries associated with the IRA account.
Request
PATCH v1/accounts/{account_id}Sample Request Body
{
"beneficiaries": [
{
"given_name": "Jane",
"middle_name": "middle",
"family_name": "Smith",
"date_of_birth": "1940-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"relationship": "spouse",
"type": "primary",
"share_pct": "50"
},
{
"given_name": "Sally",
"family_name": "Smith",
"date_of_birth": "2000-01-01",
"tax_id": "119119119",
"tax_id_type": "USA_SSN",
"relationship": "other",
"type": "primary",
"share_pct": "50"
}
]
}
Response
The existing account model returned when patching an existing account will continue to be used.
How to Process a Contribution (IRA Deposits)
Deposits to IRA accounts are considered contributions from the IRS’ perspective and Alpaca needs to collect additional data that isn't required for typical taxable brokerage accounts. The IRS sets specific contribution limits for how much a customer can deposit into their IRA account per tax year and allows contributions to the previous tax year up until the official deadline of April 15th.
Given this, Alpaca will require "tax_year" as an input parameter when depositing via ACH using our existing request transfer endpoint. If a deposit is made via a push transaction, (i.e. a wire deposit or an ACH push transaction), the system will automatically default to classify the contribution for the current tax year.
Request
POST v1/accounts/{account_id}/transfersSample Request Body
{
"transfer_type": "ach",
"relationship_id": "99eeed85-dcca-4d4b-b3ed-42d597a2f96d",
"amount": "7000",
"direction": "INCOMING",
"ira": {
"tax_year": "2024"
}
}Sample Response
The existing transfer model returned when creating a transfer will be used with the addition of a new ira object which will return the tax_year specified in the request body.
{
"id": "32a745eb-d75d-42c6-954f-575f2af768eb",
"relationship_id": "1b6bb433-3ce3-40fa-8e08-15164a408c6b",
"account_id": "9fd2c0ca-23ea-4883-ad19-f40785a0b9c5",
"type": "ach",
"status": "QUEUED",
"currency": "USD",
"amount": "143",
"instant_amount": "0",
"direction": "INCOMING",
"created_at": "2024-08-26T15:07:28.384728342-04:00",
"updated_at": "2024-08-26T15:07:28.384728342-04:00",
"expires_at": "2024-09-02T15:07:28.384008402-04:00",
"reason": null,
"hold_until": null,
"requested_amount": "143",
"fee": "0",
"fee_payment_method": "user",
"ira": {
"tax_year": "2024"
}
}How to Identify Users That Have Over Contributed
As mentioned earlier, the IRS imposes specific limits on how much a customer can contribute to their IRA in a given tax year. If a customer exceeds this limit, they may incur penalties during tax season. It’s advisable to monitor whether your customers are adhering to these IRS limits and, if not, send them a courtesy notice, guiding them to withdraw the excess funds to avoid penalties.
Alpaca simplifies this process by providing a new endpoint that allows you to pull the list of accounts that have over contributed on demand. It’s important to note that the exact limit the IRS enforces for each individual will change depending on their income bracket, tax filing status, and age – Alpaca only monitors against the maximum allowed limit by age. Since the contribution limit applies to all IRAs, including those held at other brokerages, customers are ultimately responsible for monitoring their own limits. Providing a notification to your customers as a courtesy is recommended but not required.
Request
GET v1/accounts/ira_excess_contributionsSample Response
[
{
"account_id": "e6ced109-5212-46ef-9b67-6fd93bd9f719",
"total_contribution_amount": "12000",
"tax_year": "2024"
}
]How to Process a Distribution (IRA Withdrawals)
Withdrawals from IRA accounts are considered distributions from the IRS’ perspective. Since these are designed for long term savings and retirement, there are several IRS rules that disincentivize individuals from withdrawing from an IRA account before they reach retirement age but there are limited exceptions that allow users to withdraw penalty free.
Because of this, the IRS requires we provide a reason for each distribution which must be collected from your end customer. There are also federal and state tax withholding elections that the customer must specify when requesting a distribution. As a guideline, the IRS requires 10% federal tax withholding unless the customer explicitly opts out. US state withholding requirements vary, so state-specific guidelines should be followed.
Request
POST v1/accounts/{account_id}/transfersSample Request Body
{
"transfer_type": "ach",
"relationship_id": "1b6bb433-3ce3-40fa-8e08-15164a408c6b",
"amount": "143",
"direction": "OUTGOING",
"ira": {
"distribution_reason": "normal_roth",
"tax_withholding": {
"fed_pct": "10",
"state_pct": "5.5"
}
}
}
Sample Response
The existing transfer model returned when creating a transfer will be used with the addition of a new ira object which will return the distribution_reason and tax_withholding elections specified in the request body.
{
"id": "22650ba4-04d6-4004-afb8-aac6794a902d",
"relationship_id": "1b6bb433-3ce3-40fa-8e08-15164a408c6b",
"account_id": "9fd2c0ca-23ea-4883-ad19-f40785a0b9c5",
"type": "ach",
"status": "QUEUED",
"currency": "USD",
"amount": "120.84",
"instant_amount": "0",
"direction": "OUTGOING",
"created_at": "2024-08-26T16:07:14.160737447-04:00",
"updated_at": "2024-08-26T16:07:15.476179037-04:00",
"expires_at": "2024-09-02T16:07:14.160007437-04:00",
"reason": null,
"hold_until": null,
"requested_amount": "143",
"fee": "0",
"fee_payment_method": "user",
"ira": {
"tax_year": "2024",
"fed_withholding_pct": "10",
"fed_withholding_amount": "14.3",
"state_withholding_pct": "5.5",
"state_withholding_amount": "7.86",
"distribution_reason": "normal_roth"
}
}Other Important Considerations
- Tax Documents & Required Minimum Distribution (RMD) Notices
- For IRA accounts, the primary documents provided will be tax statements and RMD notices for customers who are of RMD age. These documents will be attached to the account as an account document and available for download via the existing Broker API endpoint.
- For IRA accounts, the primary documents provided will be tax statements and RMD notices for customers who are of RMD age. These documents will be attached to the account as an account document and available for download via the existing Broker API endpoint.
- Updating Contributions and Distributions
- There may be instances where a customer needs to make a correction on a contribution or distribution from time to time. For example, if a customer made a wire deposit and could not specify the tax year for the contribution – as a result, they might want to apply it to the prior tax year vs current. For these types of cases, it’s recommended that you reach out to [email protected] to handle each correction on a case by case basis.
What’s Next?
If you are an existing partner with an interest in enabling this solution, please contact your Customer Success Manager or [email protected].
If you are not yet working with Alpaca, speak with an expert to learn more about our IRA account solution.
Additional Resources for IRAs
To learn more about IRA accounts for Broker API, see these resources:
The content of this piece article is for general information only and is believed to be accurate as of the posting date but may be subject to change. Alpaca does not provide investment, tax, or legal advice. Please consult your own independent advisor as to any investment, tax, or legal statements made herein.
All investments involve risk, and the past performance of a security, or financial product does not guarantee future results or returns. There is no guarantee that any investment strategy will achieve its objectives. Please note that diversification does not assure a profit, or protect against loss. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.
Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.
This is not an offer, solicitation of an offer, or advice to buy or sell securities or open a brokerage account in any jurisdiction where Alpaca Securities are not registered or licensed, as applicable.
Interested in learning more about Broker API?
Don't miss out on any updates about our Broker API suite of solutions! Share your details with us and be the first to know about our latest content.
