Transactions (Beta)

Transactions are used to model the flow of money into and out of a portfolio. Use the Transactions API to create and delete transactions in Addepar, retrieve, and update transaction details. You can use the View API to extract existing saved views and Query API to retrieve transactions data.

📘

Beta Feature

The base route /v1/transactions and all corresponding endpoints described herein are in the Addepar Beta Program. All beta features described herein are provided “as is'” and “as available” with no warranty or guarantee of functionality and may be modified or removed at any time by Addepar.

Please send feedback or questions to your Addepar contact.

Base route/v1/transactions
EndpointsGET
/v1/transactions/:id
/v1/transactions/:id/owner
/v1/transactions/:id/relationships/owner
/v1/transactions/:id/owned
/v1/transactions/:id/relationships/owned
/v1/transactions/:id/cash_position
/v1/transactions/:id/relationships/cash_account

POST
/v1/transactions

PATCH
/v1/transactions
/v1/transactions/:id

DELETE
/v1/transactions/:id
ProducesJSON
PaginationNo
Application Permissions Required"API Access: Create, edit, and delete"

"Portfolio Access" determines the entities that are accessible.

"Transactions" create edit and delete.

"Online transaction details" is required to update and delete online transactions.
OAuth ScopesTRANSACTIONS or TRANSACTIONS_WRITE

Resource Overview

Transactions are described by the below resource object attributes. Attributes required for creating transactions are noted.

All attributes will be returned in successful GET, POST & PATCH responses.

AttributeTypeExample
typeAddepar's classification of the transaction, which generally matches the custodian's transaction type. String.

See "Supported Transaction Types" below.
"buy"
currency Three-letter currency code, representing the currency of the cash involved in the transaction. String."USD"
trade_date The date the transaction occurred. String.

"YYYY-MM-DD "
"2020-09-25"
unitsThe number of shares of a security. Number.

Required for share-based assets.
24.48
amountDefault value for the transaction. Number.

Required for the transaction type "valuation" and value-based assets (except for "distribution" and "cash_dividend" transaction types).
1000
created_atNot editable and cannot be passed in. String."2023-07-28T02:24:30Z"
modified_atNot editable and cannot be passed in. String."2023-07-30T10:43:21Z"
Optional AttributesAdditional attributes can be applied to transactions. Multiple.

See "Optional Transaction Attributes" below.
"is_reversal": false"

Optional Transaction Attributes

AttributeDescription
posted_dateThe date that the custodian reported the transaction. String.

"YYYY-MM-DD"
settlement_dateThe date on which a trade settles. String.

"YYYY-MM-DD"
ex_dateThe date on or after which a security is traded without a previously declared dividend or distribution. String.

"YYYY-MM-DD"
descriptionA string attached to the transaction typically provided by the custodian. String.
price_factorA multiplier affecting the total value of a security. Number.
affects_cost_basisSpecifies whether cost basis / paid-in capital is affected (only applies to fees & expenses). Boolean.
affects_unfunded_commitmentA boolean specifying whether this affects unfunded commitment (only apply for fees/expenses). Boolean.
affects_adjusted_valueSpecify whether adjusted value is affected (only apply for fees/expenses). Boolean.
cancellationSpecifies whether the transaction is a cancellation of another transaction. Boolean.

Canceling a transaction does not delete it from the portfolio. Instead, canceling removes the transaction’s effects and changes the transaction type to “Cancellation.”

Deleting a transaction removes it from the portfolio entirely.
feeUsed for Total fees (should include all fee breakdowns). Number.
fee_breakdownAny specific fees that were incurred along with a transaction. It could be a brokerage fee or government tax for a transaction. Includes fee_type and fee_amount. Object. See fee breakdown below.
accruedAccrued interest. Number.
tagsAssign categories of transactions (not applicable to snapshots). [String]

Tags are append-only and cannot be removed.
commentDescribes the transaction. Max length of 4,000 characters for snapshots and 20,000 characters for all other transaction types. String.
genericAmount from an unspecified type of distribution (applicable to distribution transactions). Number.
cap_gainCapital gain of unknown term on the asset (applicable to distribution transactions). Number.
long_termLong-Term capital gains on the asset (applicable to distribution transactions). Number.
short_termShort-Term capital gains on the asset (applicable to distribution transactions). Number.
interestInterest Income earned on the asset (applicable to distribution transactions). Number.
ordinaryOrdinary income earned on the asset (applicable to distribution transactions). Number
dividendDividend income earned on the asset (applicable to distribution transactions). Number.
return_of_capitalThe return of capital from the asset (applicable to distribution transactions). Number.
recallableThe total amount of the distribution that is potentially liable to be returned to the distributor in a capital call. The recallable amount does not impact Paid-in capital.
(applicable to distribution transactions). Number.
recallable_paid_inSimilar to recallable, but the recallable amount reduces paid-in capital. (applicable to distribution transactions). Number.
option_time_valueThe underlying fee of the option (applicable to option transactions). Number.
underlying_feeThe underlying fee of an option (applicable to options transactions). Number.
vendor_idUnique identifier of a transaction as designated by a custodial data provider. Autogenerated if the transaction does not come from a data feed. String.

Fee breakdown

AttributeDescription
fee_typeFee type explains the type of the fee. String. See available fee breakdowns below.
fee_amountThe amount of the fee. Number

Available Fee types

Fee TypeKeyDescription
External Broker Feeexternal_brokerage_feeFee charged by the broker.
Internal Broker Feeinternal_brokerage_feeSelf-clearing commission or fee charged by the broker or custodian.
Other Government Taxother_government_taxCountry-specific tax other than the stamp duty or value-added tax (e.g., cantonal tax for Switzerland).
Counterparty Feecounterparty_feeFee charged by a counterparty.
Entry and Exit Feeentry_exit_feeFee charged to an investor when shares are sold from a fund, typically linked to mutual funds where the manager and the bank share a entry or exit fee tin addition to the regular transaction fee.
Foreign Feeforeign_feeForeign fee applied to the transaction.
Matching/Confirmation Feematching_feeFee levied by a transfer agent for matching and confirming trades.
Market Feemarket_feeFee applied by a government or regulatory organization (e.g., SEC fee in the United States).
Market Taxmarket_taxTax levied on a specific type of financial transaction for a particular purpose (e.g., financial transaction tax levied in Belgium or Spain).
Other Feeother_feeAny other type of fee.
Stamp Dutystamp_taxTax imposed by a government on documents required for certain types of transactions (e.g., the sale or transfer of property).
Stock Exchange Taxstock_exchange_taxTax charged by the exchange.
Stock Exchange Feestock_exchange_feeFee charged by the exchange.
Turnover Feeturnover_feeTurnover fee for the stock exchange order.
Value-Added Tax (VAT)value_added_taxTax applied to nearly all goods and services bought and sold for use or consumption.
Withholding Taxwithholding_taxTax deducted from interest earned by European Union residents on their investments made in another member state, by the state where the investment is held.
RelationshipDescription
ownerThe ID of the owning entity of the transaction.
ownedThe ID of the owned entity of the transaction.
cash_positionThe ID of the position between the owner & cash account.

Relationships

"relationships": {
      "owner": {
        "links": {
          "self": "/v1/transactions/1929/relationships/owner",
          "related": "/v1/transactions/1929/owner"
        },
        "data": {
          "type": "entities",
          "id": "117"
        }
      },
      "owned": {
        "links": {
          "self": "/v1/transactions/1929/relationships/owned",
          "related": "/v1/transactions/1929/owned"
        },
        "data": {
          "type": "entities",
          "id": "116"
        }
      },
      "cash_position": {
        "links": {
          "self": "/v1/transactions/1929/relationships/cash_position",
          "related": "/v1/transactions/1929/cash_position"
        }

Supported Transaction Types

Below are the currently supported transaction types. Supported transactions will be expanded with general availability.

TypeSecurity TypesDescription
account_feeAll but CashA fee charged to an account that affects account-level performance Does not affect security-level fees.
account_fee_advisorAll but CashA fee charged by a financial advisor. Identical to an account fee.
account_fee_bankAll but CashA fee charged by the bank. Identical to an account fee.
account_fee_custodianAll but CashA fee charged by a custodian. Identical to an account fee.
account_fee_managementAll but CashA fee charged by a manager. Identical to an account fee.
account_fee_professionalAll but CashA fee charged for professional services. Identical to an account fee.
account_fee_reimbursementAll but CashThe amount of cash returned to an investor as a reimbursement for an earlier account-level fee.
account_fee_reimbursement_advisorAll but CashA refund of an advisor fee.
account_fee_reimbursement_bankAll but CashA refund of a bank fee.
account_fee_reimbursement_custodianAll but CashA refund of a custodian fee.
account_fee_reimbursement_managementAll but CashA refund of a management fee.
account_fee_reimbursement_professionalAll but CashA refund of a professional fee.
adjustmentAll Share-BasedCreates a gain/loss on cash directly, otherwise equivalent to a buy/sell with $0 amount.
buyAll Share-Based but CashIncreases units of the security position and decreases cash on the cash position. Opens a tax lot with cost equaling the net amount of principal and fees. For fixed income securities, accrued interest can be included. It is not included in the cost basis and will be considered an expense.
capital_callManaged FundsA legally-backed demand for a fund to collect a portion of commitment from a limited partner.
cash_dividendAll but CashBy default increases security performance via income and increases cash on the cash position.
cash_in_lieuAll Share-Based but CashRemoves fractional shares and increases cash like a "sell".
change_in_unrealized_gainValue-BasedIncreases or decreases the adjusted value without affecting net cash flow.
commitmentValue-BasedIncreases total commitment on a value-based asset. No effect on cash or performance.
commitment_reductionValue-BasedDecreases total commitment on a value-based asset. No effect on cash or performance.
contributionValue-BasedIncreases the adjusted value of a value-based asset, and decreases cash (and usually the unfunded commitment) by an equal amount.
conversionShare-BasedA conversion of shares of one company's stock into shares of another company's stock. This transaction may also be used to convert a convertible note into share of stock.
corporate_actionShare-BasedA generic transaction that represents a corporate action occurring in the portfolio
cost_adjustmentValue-BasedIncreases or decreases the cost basis without affecting value or adjusted value.
cover_shortAll Share-Based but CashIdentical to a "buy".
depositCashIncreases cash units and doesn't affect performance.
distributionAll but CashDecreases adjusted value of the asset and increases cash .The amount must be allotted to a combination of the following attribute values:

"generic"

"return_of_capital"

"long_term"

"short_term"

"interest"

"ordinary"

"dividend"

"recallable"
exercise_callDerivatives only
exercise_putDerivatives onlyThe act of exercising one's right to sell the security underlying a Put Option at a given strike price.
expenseShare-Based, Value-Based, Percent-Based, CashDecreases security performance, and decreases cash. Does not affect cost basis/paid-in capital by default.
expense_allocatedManaged Funds
expirationOption, Warrant, Futures Contract, Forward ContractEquivalent to a "transfer_out" valued at $0.
fee (previouslyedge_fee)All but CashDecreases performance on the security position, and decreases cash on the cash position.
fee_reimbursement(previouslyedge_fee_reimbursement)All but CashPortions of this cost that are returned.
fund_redemption(previouslyDistribution.fund_redemption)Value-BasedIdentical to a "distribution."
gainManaged funds onlyA transaction marking the allocation of a Fund's gains or losses to its Limited Partners.
generic_flowValue-BasedIncreases or decreases adjusted value without an adjusted performance effect.
inceptionPercent-Based
incomeAllIncreases security performance and increases cash.
income_allocatedManaged Funds
interest_expenseAllDecreases security performance, and decreases cash on the cash position.
interest_incomeAllIncreases security performance increases cash on the cash position.
journal_inCashIdentical to a “deposit”.
journal_outCashIdentical to a “withdrawal”
lookthrough_adjustmentManaged Funds
mark_to_marketFutures Contract, Forward ContractIncreases or decreases the performance of the security, and, increases or decreases cash. Positive mark to market corresponds to a cash increase.
payment_made_in_lieu_of_dividendAll Share-Based but CashDecreases security performance and decreases cash on the cash position.
payment_received_in_lieu_of_dividendAll Share-Based but CashIncreases performance on the security position, and increases cash on the cash position.
proceeds_adjustmentAll Share-Based but CashIncreases the proceeds from a sell or decreases the proceeds from a buy, increasing cash.
recalled_contributionValue-BasedDecreases the adjusted value of a value-based asset, and increases cash (and usually the unfunded commitment) by an equal amount.
redemptionPreferred Stock, CMO, Bond, Certificate of DepositIdentical to a "sell", but only available on fixed income securities.
reinvestmentAll Share-Based but CashIdentical to a "buy".
sellAll Share-Based but CashDecreases units of the security position and increases cash on the cash position. Generally closes tax lots using FIFO. For Fixed Income securities, accrued interest can be included and will hit be considered an Income.
sell_shortAll Share-Based but CashIdentical to a "sell", but the resulting position will have negative units and value.
snapshotShare-BasedA marker of ownership and value of a position at a specific point in time. Snapshots can be combined with valuations, but otherwise snapshots cannot be requested with other transaction types.
spinoffShare-BasedThe creation of a brand new company via the breakout of a division or team from a parent company
stock_dividendShare-BasedA payment of stock made by a corporation to its shareholders.
stock_reverse_splitAll Share-Based but CashDecreases shares. Tax lot units are decreased on a prorated basis.
stock_splitShare-BasedAn increase in a company's total number of shares that occurs without changing the company's market capitalization and without dilution. A split transaction changes the number of shares represented in a particular position, according to the ratio of the split.
taxAll but CashDecreases security performance, and decreases cash on the cash position.
tax_refundAll but CashIncreases security performance be decreasing expense, and increases cash on the cash position.
tax_withholding(previouslyWithdrawal.tax_withholding)CashIdentical to a “withdrawal”.
tax_withholding_refund (previously Deposit.tax_withholding_refund)CashIdentical to a “deposit”.
transferAllThe movement of value (e.g. cash, stocks, etc.) from one asset, account, or legal entity to another asset, account, or legal entity.
transfer_inAllIncreases shares/cash/value. For transfers of shares, the amount field specifies the value flow into the account.
transfer_outAllIncreases shares/cash/value. For transfers of shares, the amount field specifies the value flow out of the account.
unfunded_adjustmentValue-BasedIncreases or decreases the unfunded commitment on a value-based asset. No effect on cash or performance.
valuationValue-BasedAn update to the value of an asset. Valuations can be combined with snapshots, but otherwise valuations cannot be requested with other transaction types.
withdrawalCashDecreases cash units and doesn't affect performance.
write_optionOptionFunctions like a "sell_short", but specifically for Options.
written_exercise_callDerivatives onlyThe exercise of a call option by a party opposite to your client; in other words, the sale of stock by your client to another party who has exercised an option to purchase stock from you at a particular strike price.
written_exercise_putDerivatives onlyThe exercise of a put option by a party opposite to your client; in other words, the purchase of stock by your client to another party who has exercised an option to sell stock to you at a particular strike price.
written_expirationOption, Futures Contract, Forward ContractEquivalent to a "transfer_in" valued at $0.

Supported Fee Types

Create a New Transaction

Adds a new transaction to your firm.

POST /v1/transactions

Required Fields

  • type
  • currency
  • trade_date
  • units required for share based assets
  • amount required for the transaction type "valuation" and value-based assets (except for "distribution" and "cash_dividend" transaction types).

Optional Fields

See "Optional Transaction Attributes" above.

Example:

In this example, we create a buy for a share-based asset with a trade date of "2008-03-02". A cash position has not been specified in the relationship, so cash will reflect paid from "Unknown" in the application.

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":{
      "type":"transactions",
      "attributes":{
         "amount":100010.0,
         "cancellation":false,
         "fee":10.0,
         "currency":"USD",
         "comment":"Comment 2",
         "units":1000.0,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "data":{
               "type":"entities",
               "id":"2138776"
            }
         },
         "owned":{
            "data":{
               "type":"entities",
               "id":"2363267"
            }
         }
      }
   }
}
HTTP/1.1 201 Created

{
   "data":{
      "id":"1016552763",
      "type":"transactions",
      "attributes":{
         "amount":100010.0,
         "cancellation":false,
         "vendor_id":"0a950423-0e3e-4a2b-9888-0153d0153bfd",
         "currency":"USD",
         "comment":"Comment 2",
         "units":1000.0,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/1016552763/relationships/owner",
               "related":"/v1/transactions/1016552763/owner"
            },
            "data":{
               "type":"entities",
               "id":"2138776"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/1016552763/relationships/owned",
               "related":"/v1/transactions/1016552763/owned"
            },
            "data":{
               "type":"entities",
               "id":"2363267"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/1016552763"
      }
   },
   "included":[
      
   ]
}

A buy can be created with a fee breakdown.

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":{
      "type":"transactions",
      "attributes":{
         "amount":100010.0,
         "cancellation":false,
         "fee":10.0,
         "fee_breakdown": [
          {
            "fee_type": "EXTERNAL_BROKERAGE_FEE",
            "fee_amount": 3.0
          },
          {
            "fee_type": "GENERAL_FEE",
            "fee_amount": 7.0
          }
        ],
         "currency":"USD",
         "comment":"Comment 2",
         "units":1000.0,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "data":{
               "type":"entities",
               "id":"2138776"
            }
         },
         "owned":{
            "data":{
               "type":"entities",
               "id":"2363267"
            }
         }
      }
   }
}
HTTP/1.1 201 Created

{
   "data":{
      "id":"2083",
      "type":"transactions",
      "attributes":{
         "amount":100010.0,
         "cancellation":false,
         "vendor_id":"d1f54331-4248-46b5-b002-124d175273c5",
         "fee":10,
         "fee_breakdown":[
            {
               "fee_type":"EXTERNAL_BROKERAGE_FEE",
               "fee_amount":3.0
            },
            {
               "fee_type":"INTERNAL_BROKERAGE_FEE",
               "fee_amount":4.0
            }
         ],
         "currency":"USD",
         "comment":"Comment 2",
         "units":1000,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owner",
               "related":"/v1/transactions/2083/owner"
            },
            "data":{
               "type":"entities",
               "id":"21"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owned",
               "related":"/v1/transactions/2083/owned"
            },
            "data":{
               "type":"entities",
               "id":"95"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/2083"
      }
   },
   "included":[
      
   ]
}

A cash position can be specified by including the cash_position relationship.

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":{
      "type":"transactions",
      "attributes":{
         "amount":100010.0,
         "cancellation":false,
         "fee":10.0,
         "currency":"GBP",
         "comment":"Comment 3",
         "units":1000.0,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "data":{
               "type":"entities",
               "id":"21"
            }
         },
         "cash_position":{
            "data":{
               "type":"positions",
               "id":"178"
            }
         },
         "owned":{
            "data":{
               "type":"entities",
               "id":"95"
            }
         }
      }
   }
}
HTTP/1.1 201 Created

{
   "data":{
      "id":"2083",
      "type":"transactions",
      "attributes":{
         "amount":100020,
         "cancellation":false,
         "vendor_id":"d1f54331-4248-46b5-b002-124d175273c5",
         "fee":10,
         "currency":"GBP",
         "comment":"Comment 3",
         "units":1000,
         "type":"buy",
         "trade_date":"2008-03-02"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owner",
               "related":"/v1/transactions/2083/owner"
            },
            "data":{
               "type":"entities",
               "id":"21"
            }
         },
         "cash_position":{
            "links":{
               "self":"/v1/transactions/2083/relationships/cash_position",
               "related":"/v1/transactions/2083/cash_position"
            },
            "data":{
               "type":"positions",
               "id":"178"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owned",
               "related":"/v1/transactions/2083/owned"
            },
            "data":{
               "type":"entities",
               "id":"95"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/2083"
      }
   },
   "included":[
      
   ]
}

Example:

In this example, we create a distribution for a value-based asset with a trade date of "2018-04-23" and a posted date of "2018-04-24". A short-term capital gain and generic distribution amount are reflected by including "short_term" and "generic" attribute values.

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":{
      "type":"transactions",
      "attributes":{
         "currency":"USD",
         "comment":"Comment 2",
         "type":"distribution",
         "generic":25000,
         "short_term":2000,
         "trade_date":"2018-04-23",
         "posted_date":"2018-04-24"
      },
      "relationships":{
         "owner":{
            "data":{
               "type":"entities",
               "id":"2260650"
            }
         },
         "owned":{
            "data":{
               "type":"entities",
               "id":"2260679"
            }
         }
      }
   }
}
HTTP/1.1 201 Created

{
   "data":{
      "id":"1016553122",
      "type":"transactions",
      "attributes":{
         "cancellation":false,
         "vendor_id":"7e76ea22-1ffe-46de-9f6e-70df2fb2e1f6",
         "short_term":2000.0,
         "currency":"USD",
         "comment":"Comment 2",
         "type":"distribution",
         "trade_date":"2018-04-23",
         "posted_date":"2018-04-24",
         "generic":25000.0
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/1016553122/relationships/owner",
               "related":"/v1/transactions/1016553122/owner"
            },
            "data":{
               "type":"entities",
               "id":"2260650"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/1016553122/relationships/owned",
               "related":"/v1/transactions/1016553122/owned"
            },
            "data":{
               "type":"entities",
               "id":"2260679"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/1016553122"
      }
   },
   "included":[
      
   ]
}

We can also create a valuation for "2018-04-30" to reflect the value of the position.

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":{
      "type":"transactions",
      "attributes":{
         "currency":"USD",
         "amount":50000,
         "type":"valuation",
         "trade_date":"2018-04-30"
      },
      "relationships":{
         "owner":{
            "data":{
               "type":"entities",
               "id":"2260650"
            }
         },
         "owned":{
            "data":{
               "type":"entities",
               "id":"2260679"
            }
         }
      }
   }
}
HTTP/1.1 201 Created

{
   "data":{
      "id":"26359439434990835",
      "type":"transactions",
      "attributes":{
         "amount":50000.0,
         "currency":"USD",
         "comment":"",
         "type":"valuation",
         "trade_date":"2018-04-30"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/26359439434990835/relationships/owner",
               "related":"/v1/transactions/26359439434990835/owner"
            },
            "data":{
               "type":"entities",
               "id":"2260650"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/26359439434990835/relationships/owned",
               "related":"/v1/transactions/26359439434990835/owned"
            },
            "data":{
               "type":"entities",
               "id":"2260679"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/26359439434990835"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 201 OK: Success
  • 400 Bad Request: If the generated fields are specified
  • 400 Bad Request: Non supported transaction type
  • 400 Bad Request: If the transaction fails to validate
  • 403 Forbidden: Insufficient application permissions

Create Multiple Transactions

Adds multiple transactions to your firm.

POST /v1/transactions

Required Fields

  • type
  • currency
  • trade_date
  • units required for share based assets
  • amount required for the transaction type "valuation" and value-based assets

Optional Fields

See "Optional Transaction Attributes" above.

Example:

POST https://examplefirm.addepar.com/api/v1/transactions

{
   "data":[
      {
         "type":"transactions",
         "attributes":{
            "amount":100010.0,
            "cancellation":false,
            "fee":10.0,
            "currency":"usd",
            "comment":"Comment 2",
            "units":1000.0,
            "type":"buy",
            "trade_date":"2008-03-02"
         },
         "relationships":{
            "owner":{
               "data":{
                  "type":"entities",
                  "id":"2260647"
               }
            },
            "owned":{
               "data":{
                  "type":"entities",
                  "id":"259847"
               }
            }
         }
      },
      {
         "type":"transactions",
         "attributes":{
            "posted_date":"2020-09-25",
            "trade_date":"2020-09-25",
            "type":"contribution",
            "currency":"usd",
            "description":"lorem prism",
            "amount":13.48,
            "comment":"Random comment",
            "tags":[
               "Unknown"
            ]
         },
         "relationships":{
            "owner":{
               "data":{
                  "type":"entities",
                  "id":"2260650"
               }
            },
            "owned":{
               "data":{
                  "type":"entities",
                  "id":"2260710"
               }
            }
         }
      }
   ]
}
HTTP/1.1 201 Created

{
   "data":[
      {
         "id":"1016552771",
         "type":"transactions",
         "attributes":{
            "amount":100010.0,
            "cancellation":false,
            "vendor_id":"627fbe0d-ae79-4363-b8ed-bbdcdf9ec915",
            "currency":"USD",
            "comment":"Comment 2",
            "units":1000.0,
            "type":"buy",
            "trade_date":"2008-03-02"
         },
         "relationships":{
            "owner":{
               "links":{
                  "self":"/v1/transactions/1016552771/relationships/owner",
                  "related":"/v1/transactions/1016552771/owner"
               },
               "data":{
                  "type":"entities",
                  "id":"2260647"
               }
            },
            "owned":{
               "links":{
                  "self":"/v1/transactions/1016552771/relationships/owned",
                  "related":"/v1/transactions/1016552771/owned"
               },
               "data":{
                  "type":"entities",
                  "id":"259847"
               }
            }
         },
         "links":{
            "self":"/v1/transactions/1016552771"
         }
      },
      {
         "id":"1016552772",
         "type":"transactions",
         "attributes":{
            "amount":13.48,
            "cancellation":false,
            "vendor_id":"de7bf70f-ba88-40db-9011-2261ac5481c4",
            "description":"lorem prism",
            "currency":"USD",
            "comment":"Random comment",
            "type":"contribution",
            "trade_date":"2020-09-25",
            "posted_date":"2020-09-25",
            "tags":[
               "Unknown"
            ]
         },
         "relationships":{
            "owner":{
               "links":{
                  "self":"/v1/transactions/1016552772/relationships/owner",
                  "related":"/v1/transactions/1016552772/owner"
               },
               "data":{
                  "type":"entities",
                  "id":"2260650"
               }
            },
            "owned":{
               "links":{
                  "self":"/v1/transactions/1016552772/relationships/owned",
                  "related":"/v1/transactions/1016552772/owned"
               },
               "data":{
                  "type":"entities",
                  "id":"2260710"
               }
            }
         },
         "links":{
            "self":"/v1/transactions/1016552772"
         }
      }
   ],
   "included":[
      
   ],
   "links":{
      "next":null
   }
}

Response Codes

  • 201 OK: Success
  • 400 Bad Request: If the generated fields are specified
  • 400 Bad Request: Non supported transaction type
  • 400 Bad Request: If the transaction fails to validate
  • 403 Forbidden: Insufficient application permissions

Update a Transaction

Modifies an existing transaction.

PATCH /v1/transactions/:id

The following attributes can not be updated:

  • vendor_id
  • trade_date applicable to snapshot and valuation transactions

The following relationship fields can not be updated:

  • owner
  • owned
  • cash_position

Note: If a transaction includes fee breakdown, you must include the fee breakdowns in the request.

To remove an attribute value from the transaction, set the attribute value to null.

Example:

PATCH https://examplefirm.addepar.com/api/v1/transactions/2083

{
   "data":{
      "id":"2083",
      "type":"transactions",
      "attributes":{
         "amount":999.0,
         "fee":10,
         "fee_breakdown":[
            {
               "fee_type":"EXTERNAL_BROKERAGE_FEE",
               "fee_amount":3.0
            },
            {
               "fee_type":"GENERAL_FEE",
               "fee_amount":7.0
            }
         ],
         "comment":"Edited Comment",
         "units":24.0,
         "trade_date":"2021-01-22"
      }
   }
}
HTTP/1.1 200 Success

{
   "data":{
      "id":"2083",
      "type":"transactions",
      "attributes":{
         "amount":999,
         "cancellation":false,
         "vendor_id":"d1f54331-4248-46b5-b002-124d175273c5",
         "currency":"GBP",
         "fee":10,
         "fee_breakdown":[
            {
               "fee_type":"EXTERNAL_BROKERAGE_FEE",
               "fee_amount":3.0
            },
            {
               "fee_type":"GENERAL_FEE",
               "fee_amount":7.0
            }
         ],
         "comment":"Edited Comment",
         "units":24,
         "type":"buy",
         "trade_date":"2021-01-22"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owner",
               "related":"/v1/transactions/2083/owner"
            },
            "data":{
               "type":"entities",
               "id":"21"
            }
         },
         "cash_position":{
            "links":{
               "self":"/v1/transactions/2083/relationships/cash_position",
               "related":"/v1/transactions/2083/cash_position"
            },
            "data":{
               "type":"positions",
               "id":"178"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/2083/relationships/owned",
               "related":"/v1/transactions/2083/owned"
            },
            "data":{
               "type":"entities",
               "id":"95"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/2083"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 200 OK: Success
  • 400 Bad Request: Invalid payload
  • 400 Bad Request: If the transaction fails to validate
  • 403 Forbidden: If the user does not have write access for transactions
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Update Multiple Transactions

Modifies existing transactions.

PATCH /v1/transactions

The following attributes can not be updated:

  • vendor_id
  • trade_date (cannot be updated for snapshots as it changes the transaction id)

The following relationship fields can not be updated:

  • owner
  • owned
  • cash_position

To remove an attribute value from the transaction, set the attribute value to null.

Example:

PATCH https://examplefirm.addepar.com/api/v1/transactions

{
   "data":[
      {
         "id":"1978",
         "type":"transactions",
         "attributes":{
            "cancellation":true
         }
      },
      {
         "id":"300",
         "type":"transactions",
         "attributes":{
            "description":null
         }
      }
   ]
}
HTTP/1.1 200 Success

{
   "data":[
      {
         "id":"1978",
         "type":"transactions",
         "attributes":{
            "amount":100000.0,
            "cancellation":true,
            "vendor_id":"193bd2d2-2626-401f-956d-88f083cbde19",
            "currency":"USD",
            "type":"distribution",
            "trade_date":"2020-01-02",
            "posted_date":"2020-01-02",
            "generic":100000.0
         },
         "relationships":{
            "owner":{
               "links":{
                  "self":"/v1/transactions/1978/relationships/owner",
                  "related":"/v1/transactions/1978/owner"
               },
               "data":{
                  "type":"entities",
                  "id":"208"
               }
            },
            "cash_position":{
               "links":{
                  "self":"/v1/transactions/1978/relationships/cash_position",
                  "related":"/v1/transactions/1978/cash_position"
               },
               "data":{
                  "type":"positions",
                  "id":"342"
               }
            },
            "owned":{
               "links":{
                  "self":"/v1/transactions/1978/relationships/owned",
                  "related":"/v1/transactions/1978/owned"
               },
               "data":{
                  "type":"entities",
                  "id":"213"
               }
            }
         },
         "links":{
            "self":"/v1/transactions/1978"
         }
      },
      {
         "id":"300",
         "type":"transactions",
         "attributes":{
            "amount":99980.0,
            "cancellation":false,
            "vendor_id":"d8c946f7-e515-4083-b6a2-7ef6218a4da1",
            "fee":10.0,
            "currency":"JPY",
            "units":1000.0,
            "type":"sell",
            "trade_date":"2008-10-18"
         },
         "relationships":{
            "owner":{
               "links":{
                  "self":"/v1/transactions/300/relationships/owner",
                  "related":"/v1/transactions/300/owner"
               },
               "data":{
                  "type":"entities",
                  "id":"23"
               }
            },
            "cash_position":{
               "links":{
                  "self":"/v1/transactions/300/relationships/cash_position",
                  "related":"/v1/transactions/300/cash_position"
               },
               "data":{
                  "type":"positions",
                  "id":"51"
               }
            },
            "owned":{
               "links":{
                  "self":"/v1/transactions/300/relationships/owned",
                  "related":"/v1/transactions/300/owned"
               },
               "data":{
                  "type":"entities",
                  "id":"97"
               }
            }
         },
         "links":{
            "self":"/v1/transactions/300"
         }
      }
   ],
   "included":[
      
   ],
   "links":{
      "next":null
   }
}

Response Codes

  • 200 OK: Success
  • 400 Bad Request: Invalid payload
  • 400 Bad Request: If the transaction fails to validate
  • 403 Forbidden: Insufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Get a Transaction

Returns a transaction with the given ID.

GET /v1/transactions/:id

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968
HTTP/1.1 200 Success

{
   "data":{
      "id":"1968",
      "type":"transactions",
      "attributes":{
         "created_at":"2023-07-28T02:24:30Z",
         "amount":10000,
         "cancellation":false,
         "vendor_id":"aca6bbdb-097f-46c0-b83a-709dfdae202b",
         "currency":"USD",
         "units":100,
         "type":"buy",
         "trade_date":"2019-01-02",
         "modified_at":"2023-07-30T10:43:21Z"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/transactions/1968/relationships/owner",
               "related":"/v1/transactions/1968/owner"
            },
            "data":{
               "type":"entities",
               "id":"196"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/transactions/1968/relationships/owned",
               "related":"/v1/transactions/1968/owned"
            },
            "data":{
               "type":"entities",
               "id":"200"
            }
         }
      },
      "links":{
         "self":"/v1/transactions/1968"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Get Transaction Owner Entity

Will return the owner entity of the transaction.

GET /v1/transactions/:id/owner

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968/relationships/owner
HTTP/1.1 200 Success

{
   "data":{
      "id":"196",
      "type":"entities",
      "attributes":{
         "account_number":"23975399",
         "last_verified_date":"2019-01-02",
         "currency_factor":"USD",
         "online_status":"ONLINE",
         "ownership_type":"PERCENT_BASED",
         "original_name":"Schwab Account",
         "model_type":"FINANCIAL_ACCOUNT",
         "is_rolled_up":false,
         "immediate_update_requested":"2019-07-19"
      },
      "links":{
         "self":"/v1/entities/196"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot
  • 404 Not Found: Nonexistent/non-permissioned entities IDs

Get Transaction Owner Relationship

Will return the relationship of the owner entity.

GET /v1/transactions/:id/relationships/owner

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968/relationships/owned
HTTP/1.1 200 Success

{
   "data":{
      "id":196,
      "type":"entities"
   }
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Get Transaction Owned Entity

Will return the owned entity.

GET /v1/transactions/:id/owned

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968/owned
HTTP/1.1 200 Success

{
   "data":{
      "id":"200",
      "type":"entities",
      "attributes":{
         "currency_factor":"USD",
         "ticker_symbol":[
            {
               "date":null,
               "value":"AAPL",
               "weight":1
            }
         ],
         "ownership_type":"SHARE_BASED",
         "original_name":"Apple",
         "model_type":"STOCK"
      },
      "links":{
         "self":"/v1/entities/200"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot
  • 404 Not Found: Nonexistent/non-permissioned entities IDs

Get Transaction Owned Relationship

Will return the relationship of the owned entity.

GET /v1/transactions/:id/relationships/owned

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968/relationships/owned
HTTP/1.1 200 Success

{
   "data":{
      "id":200,
      "type":"entities"
   }
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Get Transaction Cash Position

Will return the cash account entity.

GET /v1/transactions/:id/cash_position

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968/cash_position
HTTP/1.1 200 Success

{
   "data":{
      "id":"178",
      "type":"positions",
      "attributes":{
         "name":"Cash"
      },
      "relationships":{
         "owner":{
            "links":{
               "self":"/v1/positions/178/relationships/owner",
               "related":"/v1/positions/178/owner"
            },
            "data":{
               "type":"entities",
               "id":"21"
            }
         },
         "owned":{
            "links":{
               "self":"/v1/positions/178/relationships/owned",
               "related":"/v1/positions/178/owned"
            },
            "data":{
               "type":"entities",
               "id":"32"
            }
         }
      },
      "links":{
         "self":"/v1/positions/178"
      }
   },
   "included":[
      
   ]
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot
  • 404 Not Found: Nonexistent/non-permissioned entities IDs

Get Transaction Cash Position Relationship

Will return the relationship of the cash account entity.

GET /v1/transactions/:id/relationships/cash_account

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/1968
HTTP/1.1 200 Success

{
   "data":{
      "id":178,
      "type":"positions"
   }
}

Response Codes

  • 200 OK: Success
  • 404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Delete Transaction

Will delete the transaction if it exists.

DELETE /v1/transactions/:id

Example:

DELETE https://examplefirm.addepar.com/api/v1/transactions/1968
HTTP/1.1 204 No Content

Response Codes

  • 204 No Content: Success
  • 403 Forbidden: Insufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned transaction ID