Query

The Transactions Query API returns transaction data filtered by date range, portfolio scope, and attribute-based criteria. It is the primary endpoint for pulling transaction history into data warehouses, reconciliation systems, and reporting pipelines. Unlike the Transactions endpoint (which operates on individual records by ID), Transactions Query lets you retrieve many transactions at once based on who owns them, what date range they fall in, and what attributes they have.

Use this endpoint for synchronous, filtered reads. For large exports that may time out, use Transaction Jobs instead.

Overview

📘

Access requirements

• API Access: Create, edit, and delete.
• Transaction firm view: View only.
• Transactions: View-only permission to extract transaction data.

Required parameters

Alternative to portfolio_id: Pass external_ids to scope by external identifier instead of internal ID. Format: [{"external_type_key": "salesforce", "external_id": "sf_record_123"}]

Optional parameters

Query transactions

POST /v1/transactions/query

curl -X POST "https://{firm}.addepar.com/api/v1/transactions/query" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "transaction_query",
    "attributes": {
      "columns": ["direct_owner", "security", "value", "trade_date"],
      "portfolio_type": "GROUP",
      "portfolio_id": 7,
      "start_date": "2021-02-01",
      "end_date": "2021-03-01",
      "include_online_valuations": false,
      "include_unverified": false,
      "include_deleted": true
    }
  }
}'

{
  "meta": {
    "columns": ["direct_owner", "security", "value", "trade_date"]
  },
  "data": [
    {
      "id": "7",
      "type": "transaction_query",
      "attributes": {
        "direct_owner": { "name": "Person 1", "entity_id": 22 },
        "security": { "name": "Holding Company 1", "entity_id": 21 },
        "trade_date": "2000-01-01",
        "value": null
      }
    }
  ],
  "included": [],
  "links": { "next": null }
}

The response meta.columns array confirms which columns were used. Each row in data is a transaction with the requested attribute values. Entity-reference columns (like direct_owner, security) return an object with name and entity_id.

Response codes:

• 200 OK -- Query succeeded
• 400 Bad Request -- Malformed query, invalid column name, or missing required parameters
• 403 Forbidden -- Insufficient permissions or scope

Filter object

Filters narrow results by attribute value. Each filter specifies an attribute, an operator (include or exclude), a type that matches the attribute's data type, and the criteria.

Type-specific fields:

Example with discrete filter:

curl -X POST "https://{firm}.addepar.com/api/v1/transactions/query" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "transaction_query",
    "attributes": {
      "columns": ["direct_owner", "value", "trade_date"],
      "filters": [
        {
          "operator": "include",
          "type": "discrete",
          "values": ["Buy", "Sell"],
          "attribute": "type"
        }
      ],
      "portfolio_type": "firm",
      "portfolio_id": [1],
      "start_date": "2021-09-05",
      "end_date": "2021-10-05",
      "include_online_valuations": false,
      "include_unverified": false,
      "include_deleted": true
    }
  }
}'

Date filters

Date filters use a period object that defines the time window. The period type determines which additional fields are required:

Duration string format: P{count}{unit} where unit is: D (days), K (weekdays), W (weeks), M (months), Q (quarters), Y (years). Example: "P3M" = 3 months, "P2K" = 2 weekdays.

Static time period example:

{
  "attribute": "trade_date",
  "operator": "include",
  "type": "date",
  "period": {
    "type": "static_time_period",
    "start": "2020-01-02",
    "end": "2020-01-03"
  }
}

Trailing time period example:

{
  "attribute": "trade_date",
  "operator": "include",
  "type": "date",
  "period": {
    "type": "trailing_time_period",
    "period": "P2K"
  }
}

Sorting

Sort results by up to 3 columns. The order of entries in the array determines priority (first entry is the primary sort).

"sorting": [
  { "attribute": "trade_date", "ascending": false },
  { "attribute": "security", "ascending": true }
]

This sorts newest trades first, then alphabetically by security name within the same date.

Available columns

📘

Related

• Transactions -- Single-record CRUD operations
• Transaction Jobs -- Async export for large datasets
• Transaction Types -- Valid type classifications for filtering
• Attributes -- Discover available attribute keys for columns and filters
• External Identifiers -- Use external IDs as portfolio scope