Guides

Transactions

Transactions model the flow of money into and out of a portfolio, including trades, corporate actions, transfers, fees, and income distributions. Use the Transactions API to create and delete transactions in Addepar, retrieve transaction records, inspect relational entity links, and update operational details.

Overview

📘

Which Transaction API should you use?

• Transactions API (/v1/transactions): Direct record-level CRUD operations, trade lookups, sub-resource relationship inspections, and file attachments.
• Transactions Query API (/v1/transactions/query): Dynamic, multi-entity transaction searches with custom columns and date range filters.
• Transaction Views API (/v1/transactions/views): Synchronous file streaming (CSV, TSV, XLSX) using UI-configured saved transaction views.
• Transaction Jobs API (/v1/transaction_jobs): Asynchronous batch compute engine for massive date ranges or large firm-wide portfolios.
• Snapshots API (/v1/snapshots): Position-level balances, snapshot quantities, and market valuations (not supported via /v1/transactions).

FieldDetails
Base Route/v1/transactions
EndpointsGET /v1/transactions/:id
GET /v1/transactions/:id/owner
GET /v1/transactions/:id/relationships/owner
GET /v1/transactions/:id/owned
GET /v1/transactions/:id/relationships/owned
GET /v1/transactions/:id/new_owner
GET /v1/transactions/:id/relationships/new_owner
GET /v1/transactions/:id/new_owned
GET /v1/transactions/:id/relationships/new_owned
GET /v1/transactions/:id/cash_position
GET /v1/transactions/:id/relationships/cash_account
GET /v1/transactions/:id/files
POST /v1/transactions
POST /v1/transactions/:id/files
PATCH /v1/transactions
PATCH /v1/transactions/:id
DELETE /v1/transactions
DELETE /v1/transactions/:id
DELETE /v1/transactions/:id/files/:file_id
Producesapplication/vnd.api+json
PaginationBatch operations accept up to 500 transactions per request. Single reads are fetched by ID. Bulk extraction must use /query, /views, or /transaction_jobs.
Application Permissions• "API Access: Create, edit, and delete"
• "Portfolio Access" (determines accessible entities)
• "Transactions: Create, edit, and delete"
• "Online transaction details" (required to update and delete online transactions)
• "Files: Read and edit permissions" (required for file attachment routes)
OAuth ScopesTRANSACTIONS or TRANSACTIONS_WRITE (and FILES for file attachment routes)

Resource Overview

A Transaction resource models the operational, accounting, and relational attributes of an individual event. All attributes are returned in successful GET, POST, and PATCH responses.

📘

Full Object Reference
For extended property mappings, tax lots, and custom attributes, refer to the V1 Transaction Object reference.

Primary Attributes

AttributeTypeRequirementDescriptionExample
typeStringRequired (POST)Addepar classification of the transaction (e.g., buy, sell, contribution, distribution, node_fee). Immutable via PATCH."buy"
currencyStringRequired (POST)Three-letter ISO currency code representing transaction cash."USD"
trade_dateStringRequired (POST)Execution date formatted as YYYY-MM-DD. Immutable via PATCH."2020-09-25"
unitsNumberConditionalNumber of shares or units. Strictly required for share-based assets. Omit for value-based contributions.24.48
amountNumberConditionalTotal transaction gross amount. Strictly required for value-based assets, contributions, and valuation records.13.48
vendor_idStringRead-OnlyUnique identifier assigned by a custodial provider. Omit on creation. Immutable via PATCH."77d3e351-7e4e-4c9c-89d6-057de194c7ad"
created_atStringRead-OnlyUTC creation timestamp (ISO 8601). Immutable via PATCH."2023-07-28T02:24:30Z"
modified_atStringRead-OnlyUTC last modified timestamp (ISO 8601). Immutable via PATCH."2023-07-30T10:43:21Z"

Optional Operational Attributes

AttributeTypeDescriptionExample
posted_dateStringDate reported by the custodian (YYYY-MM-DD)."2020-09-25"
settlement_dateStringDate on which the cash/security settles (YYYY-MM-DD)."2020-09-27"
ex_dateStringCut-off date for dividend or income distribution rights (YYYY-MM-DD)."2020-09-20"
calculation_dateStringInternal valuation or performance calculation date (YYYY-MM-DD)."2025-05-15"
valuesObjectConverted currency values calculated by Addepar, including base currency value (values.base).{"base": 10000.0}
cancellationBooleanFlags the transaction as an economic cancellation. Setting true removes balance effects while retaining audit history.false
descriptionStringCustodial description narrative or memo. Set to null to clear."lorem prism"
commentStringInternal user note (supports up to 20,000 characters). Set to null to clear."Random comment"
tagsArray[String]Categorization tags. Append-only (existing tags cannot be deleted).["Unknown"]
price_factorNumberMultiplier affecting the calculated total value of an asset.1.0
feeNumberTotal transaction fee amount. Must equal the arithmetic sum of fee_breakdown.10.0
fee_breakdownArray[Object]Itemized fee components. Requires uppercase fee_type and numeric fee_amount.See Fee Breakdown below.
accruedNumberAccrued interest on fixed income transactions.15.50
affects_cost_basisBooleanWhether fees/expenses impact cost basis or paid-in capital.true
affects_unfunded_commitmentBooleanWhether transaction capital alters unfunded commitment balances (applicable to contributions and private fund expenses).false
affects_adjusted_valueBooleanWhether fees/expenses impact adjusted carrying value.false

Contributions and Capital Calls

Contributions model capital flows into value-based assets, including private equity funds, venture capital partnerships, direct alternative investments, and private real estate:

  • Transaction Type: Set "type": "contribution". To reverse a prior capital call, use "type": "recalled_contribution".
  • Field Requirements: Contributions require amount, currency, and trade_date. The units attribute is omitted because value-based assets track committed capital balances rather than discrete share quantities.
  • Commitment Tracking: By default, contributions increase the asset's adjusted carrying value, draw down cash, and decrease the remaining unfunded commitment on the position when affects_unfunded_commitment is true.
  • Recallable Capital: When private equity distributions include recallable capital that may be drawn down again in future capital calls, categorize those flows using the recallable or recallable_paid_in distribution breakdown fields.

Distribution Breakdown Attributes

When creating or editing distribution transactions, itemize cash amounts across tax and capital buckets:

AttributeTypeDescription
genericNumberUnspecified distribution amount.
dividendNumberDividend income earned on equity holdings.
interestNumberInterest income earned on debt holdings or cash balances.
ordinaryNumberOrdinary taxable income yield.
short_termNumberShort-term capital gain distribution.
long_termNumberLong-term capital gain distribution.
cap_gainNumberCapital gain of unclassified holding duration.
return_of_capitalNumberReturn of invested principal (reduces cost basis).
recallableNumberDistribution subject to future GP capital recall (does not reduce paid-in capital).
recallable_paid_inNumberRecallable distribution that directly reduces paid-in capital.

Validated Fee Breakdown Taxonomy

When providing fee_breakdown, each array item strictly requires an uppercase string enum token for fee_type:

Fee Type Token (fee_type)Description
EXTERNAL_BROKERAGE_FEEThird-party broker execution commission.
INTERNAL_BROKERAGE_FEESelf-clearing or custodial execution fee.
MARKET_FEERegulatory agency levy (e.g., US SEC Section 31 transaction fee).
MARKET_TAXFinancial Transaction Tax (e.g., European FTT).
STAMP_TAXDocumentary stamp tax on registered transfers.
WITHHOLDING_TAXTax deducted at source on foreign dividend or interest payments.
ENTRY_EXIT_FEEMutual fund front-end load or redemption exit charge.
COUNTERPARTY_FEEAssessment charged directly by a trade counterparty.
MATCHING_FEETransfer agent trade confirmation and matching levy.
STOCK_EXCHANGE_FEEExchange connectivity and execution platform fee.
STOCK_EXCHANGE_TAXExchange-specific turnover tax.
TURNOVER_FEEVolume-based order turnover fee.
VALUE_ADDED_TAXValue Added Tax (VAT) applied to service charges.
FOREIGN_FEECross-border foreign exchange processing charge.
OTHER_GOVERNMENT_TAXRegional or jurisdictional tax (e.g., Swiss cantonal charge).
GENERAL_FEE / OTHER_FEEMiscellaneous or general execution expense.

Relationships

RelationshipResource TypeDescription
ownerentitiesThe owning portfolio, legal entity, or account. Optional only for unassigned fee nodes. Immutable.
ownedentitiesThe underlying asset, security, or fund holding instrument. Immutable.
cash_positionpositionsThe position linking the owner entity to its cash account balance. Immutable.
new_ownerentitiesThe destination account entity in transfer and journal transactions. Immutable.
new_ownedentitiesThe resulting asset entity received in corporate actions, exchanges, or spin-offs. Immutable.

Get a Transaction

Retrieves a single transaction by ID, including attributes, calculated values, relationship links, and self links.

❗️

Snapshots and Valuations Notice
Snapshot and valuation records cannot be retrieved or mutated via /v1/transactions. Use the dedicated Snapshots API (/v1/snapshots) instead.

GET /v1/transactions/:id

Example Request

GET /api/v1/transactions/1967 HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json

Responses

  • 200 OK: Success.
{
  "data": {
    "id": "1967",
    "type": "transactions",
    "attributes": {
      "vendor_id": "007a8de4-7d72-4eca-aacd-4df4c430161d",
      "values": {
        "base": 10000.0
      },
      "currency": "USD",
      "units": 100.0,
      "type": "buy",
      "trade_date": "2019-01-02",
      "calculation_date": "2025-05-15",
      "cancellation": false,
      "comment": "Random comment",
      "tags": [
        "Unknown"
      ]
    },
    "relationships": {
      "owner": {
        "links": {
          "self": "/v1/transactions/1967/relationships/owner",
          "related": "/v1/transactions/1967/owner"
        },
        "data": {
          "type": "entities",
          "id": "196"
        }
      },
      "owned": {
        "links": {
          "self": "/v1/transactions/1967/relationships/owned",
          "related": "/v1/transactions/1967/owned"
        },
        "data": {
          "type": "entities",
          "id": "199"
        }
      },
      "cash_position": {
        "links": {
          "self": "/v1/transactions/1967/relationships/cash_position",
          "related": "/v1/transactions/1967/cash_position"
        },
        "data": {
          "type": "entities",
          "id": "315"
        }
      }
    },
    "links": {
      "self": "/v1/transactions/1967"
    }
  },
  "included": []
}
  • 404 Not Found: Nonexistent or non-permissioned transaction.

Get Transaction Relationships and Related Entities

Inspect individual related resources or retrieve their relationship linkage identifiers directly using dedicated sub-resource routes.

Supported Routes

Target ResourceEntity Details Route (GET)Relationship Linkage Route (GET)
Owner Entity/v1/transactions/:id/owner/v1/transactions/:id/relationships/owner
Owned Entity/v1/transactions/:id/owned/v1/transactions/:id/relationships/owned
New Owner Entity (Transfers)/v1/transactions/:id/new_owner/v1/transactions/:id/relationships/new_owner
New Owned Entity (Corporate Actions)/v1/transactions/:id/new_owned/v1/transactions/:id/relationships/new_owned
Cash Position/v1/transactions/:id/cash_position/v1/transactions/:id/relationships/cash_account
📘

Cash Relationship Path Discrepancy
In JSON transaction payloads, the cash relationship is keyed as cash_position, but the sub-resource route to fetch its linkage identifier is /relationships/cash_account.

Example: Get Related Owner Entity

GET /api/v1/transactions/117/owner HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

{
  "data": {
    "id": "117",
    "type": "entities",
    "attributes": {
      "currency_factor": "USD",
      "original_name": "Fund Tester",
      "model_type": "PERSON_NODE"
    },
    "links": {
      "self": "/v1/entities/117"
    }
  },
  "included": []
}

Example: Get Owner Relationship Linkage

GET /api/v1/transactions/1967/relationships/owner HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

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

Example: Get Related Owned Entity

GET /api/v1/transactions/116/owned HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

{
  "data": {
    "id": "116",
    "type": "entities",
    "attributes": {
      "currency_factor": "USD",
      "no_lookthrough": false,
      "ownership_type": "VALUE_BASED",
      "original_name": "Fund 1",
      "model_type": "MANAGED_PARTNERSHIP"
    },
    "links": {
      "self": "/v1/entities/116"
    }
  },
  "included": []
}

Example: Get Owned Relationship Linkage

GET /api/v1/transactions/1967/relationships/owned HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

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

Example: Get Related New Owned Entity (Corporate Actions)

GET /api/v1/transactions/30/new_owned HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

{
  "data": {
    "id": "30",
    "type": "entities",
    "attributes": {
      "currency_factor": "USD",
      "ownership_type": "SHARE_BASED",
      "model_type": "BOND",
      "display_name": "Bond 1 Display Name",
      "bond_type": "CORPORATE_BOND",
      "original_name": "Bond 1"
    },
    "links": {
      "self": "/v1/entities/30"
    }
  },
  "included": []
}

Example: Get New Owned Relationship Linkage

GET /api/v1/transactions/30/relationships/new_owned HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

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

Example: Get Related New Owner Entity (Transfers)

GET /api/v1/transactions/22/new_owner HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

{
  "data": {
    "id": "22",
    "type": "entities",
    "attributes": {
      "currency_factor": "USD",
      "original_name": "Person 1",
      "model_type": "PERSON_NODE"
    },
    "links": {
      "self": "/v1/entities/22"
    }
  },
  "included": []
}

Example: Get New Owner Relationship Linkage

GET /api/v1/transactions/22/relationships/new_owner HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

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

Example: Get Cash Position Resource

GET /api/v1/transactions/178/cash_position HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

{
  "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": []
}

Example: Get Cash Position Relationship Linkage

GET /api/v1/transactions/1967/relationships/cash_account HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json
HTTP/1.1 200 OK

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

Create Transactions (Single or Batch up to 500)

Creates one or more transactions. You can pass a single transaction object or an array of up to 500 transactions within the data envelope.

❗️

Auto-Generated Fields Guardrail
Omit id and vendor_id from the creation payload. Passing either field causes the API to reject the request with 400 Bad Request.

POST /v1/transactions

Example Request: Batch Trades & Capital Contributions

This batch payload demonstrates creating both a share-based asset trade (buy requiring units) and a value-based private fund capital call (contribution requiring amount and setting affects_unfunded_commitment):

POST /api/v1/transactions HTTP/1.1
Host: examplefirm.addepar.com
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "transactions",
      "attributes": {
        "posted_date": "2020-09-25",
        "trade_date": "2020-09-25",
        "calculation_date": "2025-05-15",
        "type": "buy",
        "currency": "USD",
        "description": "lorem prism",
        "units": 24.48,
        "amount": 13.48,
        "fee": 10.0,
        "fee_breakdown": [
          {
            "fee_type": "EXTERNAL_BROKERAGE_FEE",
            "fee_amount": 3.0
          },
          {
            "fee_type": "INTERNAL_BROKERAGE_FEE",
            "fee_amount": 7.0
          }
        ],
        "comment": "Strategic rebalance buy",
        "tags": [
          "Equity"
        ]
      },
      "relationships": {
        "owner": {
          "data": {
            "type": "entities",
            "id": "183"
          }
        },
        "owned": {
          "data": {
            "type": "entities",
            "id": "184"
          }
        },
        "cash_position": {
          "data": {
            "type": "positions",
            "id": "178"
          }
        }
      }
    },
    {
      "type": "transactions",
      "attributes": {
        "type": "contribution",
        "currency": "USD",
        "trade_date": "2020-09-25",
        "posted_date": "2020-09-25",
        "calculation_date": "2025-05-15",
        "amount": 50000.0,
        "affects_unfunded_commitment": true,
        "comment": "Capital Call - Series IV Partnership"
      },
      "relationships": {
        "owner": {
          "data": {
            "type": "entities",
            "id": "2260650"
          }
        },
        "owned": {
          "data": {
            "type": "entities",
            "id": "2260710"
          }
        }
      }
    }
  ]
}

Example Request: Account Fee with No Owner ID

Certain transaction types (such as account-level custody or advisory fees classified as node_fee) apply directly to an asset holding without requiring an owner relationship:

POST /api/v1/transactions HTTP/1.1
Host: examplefirm.addepar.com
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": 1000.0,
      "currency": "USD",
      "type": "node_fee",
      "trade_date": "2021-04-01"
    },
    "relationships": {
      "owned": {
        "data": {
          "type": "entities",
          "id": "212"
        }
      }
    }
  }
}

Responses

  • 201 Created: Successfully created transaction(s). Returns the created resource object(s) with assigned IDs.
{
  "data": {
    "id": "1977",
    "type": "transactions",
    "attributes": {
      "amount": 13.48,
      "cancellation": false,
      "vendor_id": "77d3e351-7e4e-4c9c-89d6-057de194c7ad",
      "description": "lorem prism",
      "currency": "USD",
      "units": 24.48,
      "type": "buy",
      "trade_date": "2020-09-25",
      "posted_date": "2020-09-25",
      "calculation_date": "2025-05-15",
      "comment": "Strategic rebalance buy",
      "tags": [
        "Equity"
      ]
    },
    "relationships": {
      "owner": {
        "links": {
          "self": "/v1/transactions/1977/relationships/owner",
          "related": "/v1/transactions/1977/owner"
        },
        "data": {
          "type": "entities",
          "id": "183"
        }
      },
      "owned": {
        "links": {
          "self": "/v1/transactions/1977/relationships/owned",
          "related": "/v1/transactions/1977/owned"
        },
        "data": {
          "type": "entities",
          "id": "184"
        }
      }
    },
    "links": {
      "self": "/v1/transactions/1977"
    }
  },
  "included": []
}
  • 400 Bad Request: Auto-generated fields (id, vendor_id) specified, unsupported transaction classification, missing required parameters, or arithmetic mismatch between fee and fee_breakdown.
  • 403 Forbidden: Caller lacks transaction write permissions.
  • 409 Conflict: Payload type is not specified as "transactions".

Edit Transactions (Single or Batch up to 500)

Updates attributes of existing transactions. Modify a single transaction by ID via PATCH /v1/transactions/:id or submit an array of up to 500 updates via PATCH /v1/transactions.

Immutability & Validation Guardrails

  • Immutable Attributes: vendor_id, type, trade_date, created_at, modified_at. Attempting to alter these fields returns 400 Bad Request.
  • Immutable Relationships: owner, owned, cash_position, new_owner, new_owned cannot be modified via PATCH.
  • Clearing Optional Fields: To clear an optional attribute (e.g., description), explicitly pass "attribute_name": null.
  • Fee Array Replacement: If modifying fees, the entire fee_breakdown array must be supplied; array items cannot be patched incrementally.

PATCH /v1/transactions/:id (Single)

PATCH /v1/transactions (Batch up to 500)

Example Request (Batch Update with Cancellation & Field Removal)

PATCH /api/v1/transactions HTTP/1.1
Host: examplefirm.addepar.com
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1978",
      "type": "transactions",
      "attributes": {
        "cancellation": true
      }
    },
    {
      "id": "300",
      "type": "transactions",
      "attributes": {
        "description": null,
        "calculation_date": "2025-05-15"
      }
    }
  ]
}

Responses

  • 200 OK: Successfully modified transaction(s). Returns updated transaction array.
{
  "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
  }
}
  • 400 Bad Request: Attempted to update an immutable field, or payload failed validation.
  • 403 Forbidden: Caller lacks transaction write permissions.
  • 404 Not Found: Nonexistent or non-permissioned transactions.

Delete Transactions (Single or Batch up to 500)

Permanently removes transaction records from your firm.

❗️

Hard Delete vs. Soft Cancellation
Deleting a transaction permanently purges the record. To negate the economic balance impact while preserving compliance audit logs, update the record with "cancellation": true via PATCH instead.

DELETE /v1/transactions/:id (Single)

DELETE /v1/transactions (Batch up to 500)

Example Request (Batch Delete)

DELETE /api/v1/transactions HTTP/1.1
Host: examplefirm.addepar.com
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "103",
      "type": "transactions"
    },
    {
      "id": "104",
      "type": "transactions"
    }
  ]
}

Responses

  • 204 No Content: Successfully deleted transaction(s).
  • 400 Bad Request: Invalid payload.
  • 403 Forbidden: Inadequate permission to delete transaction(s).
  • 404 Not Found: Nonexistent or non-permissioned transaction ID(s).

Manage Transaction File Attachments

Attach, inspect, and detach documents associated with a specific transaction.

Operational Prerequisites

Permissions: Requires TRANSACTIONS read access (or TRANSACTIONS_WRITE) and FILES edit permissions.

1. List Attachments

Retrieves visible document metadata attached to a transaction.

📘

Unwrapped Envelope
Unlike the standalone /v1/files endpoint, the transaction attachment response is not wrapped in a top-level documents container. It directly returns visible, can_manage_files, and the items array.

GET /v1/transactions/:id/files

Example Request

GET /api/v1/transactions/1968/files HTTP/1.1
Host: examplefirm.addepar.com
Accept: application/vnd.api+json

Responses

  • 200 OK: Successfully retrieved the visible attachments.
{
  "data": {
    "visible": true,
    "can_manage_files": true,
    "items": [
      {
        "id": "42",
        "type": "files",
        "attributes": {
          "filename": "trade_confirmation_1968.pdf",
          "size": 1048576,
          "content_type": "application/pdf",
          "created_at": "2024-03-15T12:00:00Z"
        }
      }
    ]
  }
}
  • 403 Forbidden: Inadequate transaction or Files permission, or PII masking is enabled.
  • 404 Not Found: The transaction is unavailable, or the attachment feature is disabled.

2. Attach a File

Attaches an existing file to the specified transaction. This operation is idempotent.

POST /v1/transactions/:id/files

Example Request

POST /api/v1/transactions/1968/files HTTP/1.1
Host: examplefirm.addepar.com
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "42",
    "type": "files"
  }
}

Responses

  • 204 No Content: Successfully attached the file.
  • 400 Bad Request: Invalid request.
  • 403 Forbidden: Inadequate transaction or Files permission, or PII masking is enabled.
  • 404 Not Found: The transaction or file is unavailable, or the attachment feature is disabled.
  • 409 Conflict: The POST relationship type is not files.

3. Detach a File

Removes the attachment link between a document and a transaction. Detaching only removes the association; it does not delete the underlying file record from Addepar.

DELETE /v1/transactions/:id/files/:file_id

Example Request

DELETE /api/v1/transactions/1968/files/42 HTTP/1.1
Host: examplefirm.addepar.com

Responses

  • 204 No Content: Successfully detached the file.
  • 403 Forbidden: Inadequate transaction or Files permission.
  • 404 Not Found: The attachment or transaction does not exist.

Updated about 1 hour ago

Did this page help you?