Propose a classified cash contribution, distribution, excess return, original-receipt rollover or same-wrapper trustee transfer
/accounts/{id}/retirement-commandsFresh dedicated retirement writer, then different retirement approver. Single-owner USD traditional/Roth IRA or HSA cash deposits only. Contribution, distribution, timely return_excess and rollover use the same consumer's ordinary bank account. trustee_transfer instead names a same-owner retirement destination with the identical wrapper/IRA type. Exact current eligibility/rule, owner instruction/policy evidence, account ownership and tax classification are rechecked. Rollovers name the actually executed original distribution, preserve its calendar receipt date, require current complete outside inventory, conserve original gross cash across bank/outside portions, and enforce the 60-day and one-year receipt windows. All IRAs share the IRA count. The bounded HSA flow accepts one complete return; traditional RMD-age sources, split HSA returns, waivers, inherited and external-custody cases refuse. A conversion instead requires a same-owner traditional-to-Roth cash pair, reviewed exact owner instruction/policy and zero-withholding election. Verified DOB and a reviewed effective RMD policy determine age; every supported required year needs current approved source-complete RMD clearance before conversion, even when the first-year deadline is deferred. Pre-2026 required-year history refuses until reconciled. Direct trustee transfers do not count as paid distributions or regular contributions. beneficiary_distribution uses separate death/contract/election/tax evidence: original pre-death traditional cash IRA title, one verified adult 100-percent beneficiary, death before RBD, and full cash settlement by the end of the following year. Current sole beneficiary destination ownership and active reviewed death restriction are required; native ledger locks enforce the entire actual source balance, with optional withholding. death_transfer, death_distribution and inherited_distribution instead move a deceased holder's cash under approved beneficiary classifications (see the classification route): a transfer moves the entire protected balance into same-wrapper separate accounts pro rata and reports nothing, an HSA that ceased at death is distributed with Form 1099-SA codes 4 or 6 and the date-of-death value, and an inherited distribution pays a beneficiary with Form 1099-R code 4. recharacterization moves an executed contribution and its reviewed net income to the owner's IRA of the other type by the reviewed return due date, reporting box 1, zero in box 2a and code N or R, with the receiving IRA's Form 5498 box 4 for the year it received the amount (Notice 2000-30, Example 2). custodian_transfer sends cash directly to a receiving trustee into the source's own plan type (receiving_plan_type; a conversion or another plan type refuses), credits the payments-in-transit liability and registers a payable for the payments remittance, reporting nothing; an inherited account may only move to an inherited title, an owner at the applicable age needs paid RMD clearance, and a final distribution year refuses. rollover may instead repay another custodian's evidenced distribution the owner received (outside_original), reported as a rollover receipt. custodian_transfer_in applies one actual wire or ACH receipt payments parked on transit for this protected account to an approved inbound transfer instruction the delivering custodian accepted: the receipt must come from the confirmed sending institution on the confirmed rail, quote the instruction's match reference, arrive on or after the custodian's distribution date and fit the reviewed maximum with the instruction's other receipts. It carries no eligibility, withholding or contribution attributes, claims the receipt at payments before posting, debits GL 2320 and credits the protected account, and reports nothing on Form 5498 or 5498-SA. Cash a traditional IRA custodian released in an earlier year needs the December 31 balance adjustment of 26 CFR 1.408-8(d), which is not serviced: such a transfer refuses when that year's requirement is already approved, and later requirement reviews for the year refuse while it stands.
Path parameters
idstringRequiredHeaders
Idempotency-KeystringRequiredSend on every write that creates or changes money or state; a replay with the same key returns the original result with 200.
Body parameters
beneficiary_paymentobject or nullOptionalBeneficiaryPaymentEvidence supports full cash settlement to the sole adult individual named in the original IRA title, with death before the owner's RBD.
15 child attributes
authority_refstringRequiredauthority_sha256stringRequiredauthority_valid_untilstring · date-timeRequiredcustomer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
death_report_idstringRequiredExample strp_2tVh8nqLxq4GbDe0K1F6S9zRcWm
death_revisionintegerRequiredelection_refstringRequiredelection_sha256stringRequiredjurisdictionstringRequiredminimum_recipient_ageintegerRequiredpolicy_refstringRequiredpolicy_sha256stringRequiredrestriction_idstringRequiredrmd_policy_idstringRequiredtax_rule_idstringRequiredconversionobject or nullOptionalConversionEvidence authorizes only an immediate same-bank cash conversion. It does not authorize a recharacterization, inherited transfer or 60-day deposit.
7 child attributes
as_of_datestring · dateRequiredA business date, YYYY-MM-DD
authority_refstringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpolicy_sha256stringRequiredrmd_policy_idstringRequiredrmd_review_idsarray of stringsOptionalcustodianobject or nullOptionalCustodianTransferEvidence retains the successor trustee's acceptance of a direct transfer that involves no payment to the owner or beneficiary. ReceivingPlanType is the plan the successor trustee accepted into, which must be the source's own plan type.
14 child attributes
acceptance_refstringRequiredacceptance_sha256stringRequiredinheritance_idstringOptionalinherited_rmd_review_idstringOptionalinherited_titlebooleanRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpayee_referencestringRequiredreceiving_account_referencestringRequiredreceiving_custodianstringRequiredreceiving_plan_typestringRequiredreceiving_title_sha256stringRequiredrmd_policy_idstringOptionalrmd_review_idsarray of stringsOptionalearnings_minorintegerOptionalEvidenced signed net income attributable, return_excess only
eligibility_idstringRequiredevidence_refstringRequiredevidence_sha256stringRequiredinbound_transferobject or nullOptionalInboundReceiptEvidence names the payments receipt a custodian_transfer_in applies.
3 child attributes
railstringRequiredWire or ach
receipt_idstringRequiredExample achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm
transfer_idstringRequiredExample acht_2tVh8nqLxq4GbDe0K1F6S9zRcWm
income_tax_yearintegerOptionalReturn_excess income attribution, reviewed against tax code
inheritanceobject or nullOptionalInheritanceCommandEvidence authorizes death_transfer and death_distribution (every captured beneficiary in title order) and inherited_distribution (one).
8 child attributes
account_idsarray of stringsOptionalauthority_refstringOptionalauthority_sha256stringOptionalauthority_valid_untilstring · date-timeRequiredinheritance_idsarray of stringsRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredtax_rule_idstringOptionalkindstringRequiredContribution, distribution, return_excess, rollover, trustee_transfer, conversion, beneficiary_distribution, death_transfer, death_distribution, inherited_distribution, recharacterization, custodian_transfer, custodian_transfer_in
medical_use_attestedbooleanOptionalEvidence only: trustee does not determine HSA expense deductibility
movementobject or nullOptional10 child attributes
authority_refstringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredordinary_owner_cash_onlybooleanRequiredoutside_inventory_as_ofstring · dateOptionalA business date, YYYY-MM-DD
outside_inventory_completebooleanRequiredoutside_originalobject or nullOptionalOutsideDistribution is another custodian's actual distribution that the owner received and is redepositing here, evidenced by that custodian's own statement.
8 child attributes
custodianstringRequireddistribution_datestring · dateRequiredA business date, YYYY-MM-DD
gross_minorintegerRequiredira_typestringOptionalreferencestringRequiredstatement_refstringRequiredstatement_sha256stringRequiredwrapperstringRequiredoutside_rolloversarray of objectsOptional6 child attributes
amount_minorintegerRequiredcontribution_datestring · dateRequiredA business date, YYYY-MM-DD
distribution_datestring · dateRequiredA business date, YYYY-MM-DD
original_bank_command_idstringOptionalreferencestringRequiredwrapperstringRequiredpolicy_sha256stringRequiredrmd_policy_idstringOptionaloriginal_command_idstringOptionalThe bank's original regular contribution
other_account_idstringRequiredSame-owner ordinary account; trustee_transfer/conversion name the protected destination
Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
principal_minorintegerRequiredreasonstringRequiredrecharacterizationobject or nullOptionalRecharacterizationEvidence retains the owner's election and the reviewed net income attributable; the trustee does not calculate that income here.
6 child attributes
authority_refstringRequiredearnings_refstringRequiredearnings_sha256stringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpolicy_sha256stringRequiredtax_yearintegerRequiredwithholding_bpsinteger or nullOptionalNil uses reviewed traditional-IRA nonperiodic default
withholding_election_refstringOptionalwithholding_election_sha256stringOptionalReturns
200 OK
account_idstringRequiredExample acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
cash_datestring · dateOptionalA business date, YYYY-MM-DD
conversion_rmdarray of objectsOptional7 child attributes
bank_command_idsarray of stringsRequiredbank_paid_minorintegerRequiredoutside_paid_minorintegerRequiredrequired_minorintegerRequiredreview_idstringRequiredreview_sha256stringRequiredtax_yearintegerRequiredcustomer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
decedent_customer_idstringOptionalExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
decided_atstring · date-time or nullOptionaldecided_bystringOptionaldistribution_codestringOptionalexecuted_atstring · date-time or nullOptionalgross_minorintegerRequiredidstringRequiredinbound_receiptobject or nullOptionalInboundReceipt is the matched receipt as the command relies on it.
12 child attributes
amount_minorintegerRequiredconfirmation_idstringRequireddelivering_referencestringRequireddistribution_datestring · dateRequiredA business date, YYYY-MM-DD
outstanding_at_year_endbooleanRequiredrailstringRequiredreceipt_idstringRequiredExample achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm
received_onstring · dateRequiredA business date, YYYY-MM-DD
referencestringRequiredsender_namestringRequiredsender_routingstringRequiredtransfer_idstringRequiredExample acht_2tVh8nqLxq4GbDe0K1F6S9zRcWm
ira_typestringOptionaljournal_idstringOptionalExample jrnl_2tVh8nqLxq4GbDe0K1F6S9zRcWm
origin_cash_datestring · dateOptionalA business date, YYYY-MM-DD
other_ownership_revisionintegerRequiredownership_revisionintegerRequiredproposed_atstring · date-timeRequiredproposed_bystringRequiredrecipientsarray of objectsOptional7 child attributes
account_idstringRequiredExample acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
amount_minorintegerRequiredcustomer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
distribution_codestringOptionalinheritance_idstringRequiredownership_revisionintegerRequiredshare_bpsintegerRequiredrequestobjectRequired22 child attributes
beneficiary_paymentobject or nullOptionalBeneficiaryPaymentEvidence supports full cash settlement to the sole adult individual named in the original IRA title, with death before the owner's RBD.
15 child attributes
authority_refstringRequiredauthority_sha256stringRequiredauthority_valid_untilstring · date-timeRequiredcustomer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
death_report_idstringRequiredExample strp_2tVh8nqLxq4GbDe0K1F6S9zRcWm
death_revisionintegerRequiredelection_refstringRequiredelection_sha256stringRequiredjurisdictionstringRequiredminimum_recipient_ageintegerRequiredpolicy_refstringRequiredpolicy_sha256stringRequiredrestriction_idstringRequiredrmd_policy_idstringRequiredtax_rule_idstringRequiredconversionobject or nullOptionalConversionEvidence authorizes only an immediate same-bank cash conversion. It does not authorize a recharacterization, inherited transfer or 60-day deposit.
7 child attributes
as_of_datestring · dateRequiredA business date, YYYY-MM-DD
authority_refstringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpolicy_sha256stringRequiredrmd_policy_idstringRequiredrmd_review_idsarray of stringsOptionalcustodianobject or nullOptionalCustodianTransferEvidence retains the successor trustee's acceptance of a direct transfer that involves no payment to the owner or beneficiary. ReceivingPlanType is the plan the successor trustee accepted into, which must be the source's own plan type.
14 child attributes
acceptance_refstringRequiredacceptance_sha256stringRequiredinheritance_idstringOptionalinherited_rmd_review_idstringOptionalinherited_titlebooleanRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpayee_referencestringRequiredreceiving_account_referencestringRequiredreceiving_custodianstringRequiredreceiving_plan_typestringRequiredreceiving_title_sha256stringRequiredrmd_policy_idstringOptionalrmd_review_idsarray of stringsOptionalearnings_minorintegerOptionalEvidenced signed net income attributable, return_excess only
eligibility_idstringRequiredevidence_refstringRequiredevidence_sha256stringRequiredinbound_transferobject or nullOptionalInboundReceiptEvidence names the payments receipt a custodian_transfer_in applies.
3 child attributes
railstringRequiredWire or ach
receipt_idstringRequiredExample achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm
transfer_idstringRequiredExample acht_2tVh8nqLxq4GbDe0K1F6S9zRcWm
income_tax_yearintegerOptionalReturn_excess income attribution, reviewed against tax code
inheritanceobject or nullOptionalInheritanceCommandEvidence authorizes death_transfer and death_distribution (every captured beneficiary in title order) and inherited_distribution (one).
8 child attributes
account_idsarray of stringsOptionalauthority_refstringOptionalauthority_sha256stringOptionalauthority_valid_untilstring · date-timeRequiredinheritance_idsarray of stringsRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredtax_rule_idstringOptionalkindstringRequiredContribution, distribution, return_excess, rollover, trustee_transfer, conversion, beneficiary_distribution, death_transfer, death_distribution, inherited_distribution, recharacterization, custodian_transfer, custodian_transfer_in
medical_use_attestedbooleanOptionalEvidence only: trustee does not determine HSA expense deductibility
movementobject or nullOptional10 child attributes
authority_refstringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredordinary_owner_cash_onlybooleanRequiredoutside_inventory_as_ofstring · dateOptionalA business date, YYYY-MM-DD
outside_inventory_completebooleanRequiredoutside_originalobject or nullOptionalOutsideDistribution is another custodian's actual distribution that the owner received and is redepositing here, evidenced by that custodian's own statement.
8 child attributes
custodianstringRequireddistribution_datestring · dateRequiredA business date, YYYY-MM-DD
gross_minorintegerRequiredira_typestringOptionalreferencestringRequiredstatement_refstringRequiredstatement_sha256stringRequiredwrapperstringRequiredoutside_rolloversarray of objectsOptional6 child attributes
amount_minorintegerRequiredcontribution_datestring · dateRequiredA business date, YYYY-MM-DD
distribution_datestring · dateRequiredA business date, YYYY-MM-DD
original_bank_command_idstringOptionalreferencestringRequiredwrapperstringRequiredpolicy_sha256stringRequiredrmd_policy_idstringOptionaloriginal_command_idstringOptionalThe bank's original regular contribution
other_account_idstringRequiredSame-owner ordinary account; trustee_transfer/conversion name the protected destination
Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
principal_minorintegerRequiredreasonstringRequiredrecharacterizationobject or nullOptionalRecharacterizationEvidence retains the owner's election and the reviewed net income attributable; the trustee does not calculate that income here.
6 child attributes
authority_refstringRequiredearnings_refstringRequiredearnings_sha256stringRequiredinstruction_refstringRequiredinstruction_sha256stringRequiredpolicy_sha256stringRequiredtax_yearintegerRequiredwithholding_bpsinteger or nullOptionalNil uses reviewed traditional-IRA nonperiodic default
withholding_election_refstringOptionalwithholding_election_sha256stringOptionalstatusstringRequiredtaxable_minorinteger or nullOptionaltaxable_undeterminedbooleanRequiredwithheld_minorintegerRequiredwrapperstringRequiredErrors
Every error is a problem document with a stable code. See Errors.
400401403404409412413422424429500503