Benchmarks

Benchmarks are standards for measuring portfolio performance. A benchmark can be a market index, a fixed return, a blend of other benchmarks, or the performance of a specific security or portfolio.

Use this API to create, read, update, and delete benchmarks.

Overview


Base route	`/v1/benchmarks`
Produces	JSON
Pagination	500 records per page
OAuth scopes	`BENCHMARKS_READ` or `BENCHMARKS_WRITE`

📘
Access requirements

"API Access: Create, edit, and delete"

"Portfolio Access" determines which entities are accessible

"Benchmark library"

Benchmark types

Type	Description	Created via API?
`blended`	Weighted combination of other benchmarks. Rebalanced on a configurable interval.	Yes
`imported`	Custom daily returns provided by the firm.	Yes
`fixed_return`	Fixed annual return (e.g., 15% year-over-year).	Yes
`portfolio_benchmark`	Based on the performance of a specific portfolio entity.	Yes
`security_benchmark`	Based on the performance of a specific investment entity.	Yes
`index`	Vendor-provided market index. Only the display name can be updated.	No

Resource attributes

Attribute	Type	Description
`id`	Number	Unique benchmark identifier.
`benchmark_type`	String	One of: `blended`, `imported`, `fixed_return`, `portfolio_benchmark`, `security_benchmark`, `INDEX`. Immutable after creation.
`name`	String	Display name. Required for all types except `fixed_return` (auto-generated).

Blended-specific:

Attribute	Type	Description
`rebalance_interval`	String	`None`, `ONE_DAY`, `ONE_WEEK`, `ONE_MONTH`, `THREE_MONTHS`, `SIX_MONTHS`, `ONE_YEAR`. Required.
`benchmark_composition_id`	Number	Links to the composition resource. Always equals the benchmark's own ID. Read-only.

Fixed return-specific:

Attribute	Type	Description
`fixed_return`	Number	Annual return as a decimal (e.g., `0.15` = 15%). Up to 17 decimal places. Required.
`is_compounded`	Boolean	Whether the return compounds. Required.

Portfolio and security-specific:

Attribute	Type	Description
`entity_id`	Number	Entity ID the benchmark tracks. Portfolio: must be Household, Client, Holding Company, Trust, Fund, Holding Account, Managed Fund, or Sleeve. Security: must be an investment type (Stock, ETF, Mutual Fund, Bond, etc.). Immutable.

Index-specific (read-only except name):

Attribute	Type	Description
`vendor_id`	Number	Vendor identifier for the index.
`index_type`	String	`Index Return`, `Index Return (Estimated)`, `Index Return (Preliminary)`, `Total Return`, `Net Return`, `Hedged Return`, `Total Return - MTD`.
`index_name`	String	Original index name from vendor.
`start_date`	String	Earliest date with returns data (`YYYY-MM-DD`).
`end_date`	String	Most recent date with returns data (`YYYY-MM-DD`).

Get all benchmarks

Returns a paginated list of all active benchmarks.

GET /v1/benchmarks

curl -X GET "https://{firm}.addepar.com/api/v1/benchmarks" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1"

{
  "data": [
    {
      "id": "421",
      "type": "benchmarks",
      "attributes": {
        "benchmark_type": "INDEX",
        "name": "tr USNTBIROR",
        "index": {
          "vendor": "tr",
          "vendor_id": "USNTBIROR",
          "index_type": "INDEX",
          "index_name": "tr USNTBIROR",
          "start_date": null,
          "end_date": null
        }
      },
      "links": { "self": "/v1/benchmarks/421" }
    },
    {
      "id": "571",
      "type": "benchmarks",
      "attributes": {
        "blended": {
          "rebalance_interval": "ONE_DAY",
          "benchmark_composition_id": 571
        },
        "benchmark_type": "BLENDED",
        "name": "Default-BB"
      },
      "links": { "self": "/v1/benchmarks/571" }
    }
  ],
  "included": [],
  "links": { "prev": null, "next": null }
}

Response codes:

200 OK -- Success
403 Forbidden -- No permission to view benchmarks

Get a benchmark

GET /v1/benchmarks/:id

Response codes:

200 OK -- Success
404 Not Found -- No benchmark with this ID

Create a benchmark

Creates a new benchmark. Index benchmarks cannot be created via the API.

POST /v1/benchmarks

All types require benchmark_type and name (except fixed_return, which auto-generates the name). Type-specific fields are listed below.

Type	Required fields
`blended`	`blended.rebalance_interval`
`fixed_return`	`fixed_return.fixed_return`, `fixed_return.is_compounded`
`portfolio_benchmark`	`portfolio.entity_id` (must be Household, Client, Holding Company, Trust, Fund, Holding Account, Managed Fund, or Sleeve)
`security_benchmark`	`security.entity_id` (must be an investment type)
`imported`	No additional fields

curl -X POST "https://{firm}.addepar.com/api/v1/benchmarks" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -d '{
    "data": [
      {
        "type": "benchmarks",
        "attributes": {
          "benchmark_type": "blended",
          "name": "60/40 Equity-Fixed",
          "blended": {
            "rebalance_interval": "three_months"
          }
        }
      }
    ]
  }'

{
  "data": {
    "id": "571",
    "type": "benchmarks",
    "attributes": {
      "blended": {
        "rebalance_interval": "THREE_MONTHS",
        "benchmark_composition_id": 571
      },
      "benchmark_type": "BLENDED",
      "name": "60/40 Equity-Fixed"
    },
    "links": { "self": "/v1/benchmarks/571" }
  },
  "included": []
}

📘
Blended benchmark compositions
The benchmark_composition_id always equals the benchmark's own ID. Use it with the Benchmark Compositions endpoint to define or update the underlying weighted components.

Response codes:

200 OK -- Success
400 Bad Request -- Invalid payload or missing required field
403 Forbidden -- No permission to create benchmarks
409 Conflict -- A benchmark with the same name already exists

Edit benchmarks

Updates one or more existing benchmarks. Single: /v1/benchmarks/:id. Bulk: /v1/benchmarks with an array body.

PATCH /v1/benchmarks/:id or PATCH /v1/benchmarks

Immutable fields (cannot be updated):

Type	Immutable fields
All	`benchmark_type`
Blended	`benchmark_composition_id`
Portfolio / Security	`entity_id`
Index	All fields except `name` (`vendor`, `vendor_id`, `index_type`, `index_name`, `start_date`, `end_date`)

curl -X PATCH "https://{firm}.addepar.com/api/v1/benchmarks/739" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -d '{
    "data": {
      "id": "739",
      "type": "benchmarks",
      "attributes": {
        "fixed_return": {
          "fixed_return": 0.15,
          "is_compounded": false
        }
      }
    }
  }'

curl -X PATCH "https://{firm}.addepar.com/api/v1/benchmarks" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -d '{
    "data": [
      {
        "id": "739",
        "type": "benchmarks",
        "attributes": {
          "fixed_return": { "fixed_return": 0.17, "is_compounded": true }
        }
      },
      {
        "id": "571",
        "type": "benchmarks",
        "attributes": {
          "blended": { "rebalance_interval": "six_months" }
        }
      }
    ]
  }'

Response codes:

200 OK -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- No permission to update benchmarks
404 Not Found -- Benchmark does not exist
409 Conflict -- A benchmark with the same name already exists

Delete a benchmark

Deletes a user-created benchmark. Fixed return and index benchmarks cannot be deleted.

DELETE /v1/benchmarks/:id

⚠️
Warning
Deleting a benchmark breaks downstream references (reports, compositions, associations). This action cannot be undone.

Response codes:

204 No Content -- Deleted
400 Bad Request -- Benchmark type cannot be deleted (fixed return or index)
403 Forbidden -- No permission to delete benchmarks
404 Not Found -- Benchmark does not exist

📘
Related

Benchmark Compositions -- Weighted components underlying blended benchmarks

Imported Benchmark Data -- Daily returns for imported benchmarks

Benchmark Associations Strategies -- Link benchmarks to portfolio strategies

Benchmarks

Overview

📘
Access requirements

Benchmark types

Resource attributes

Get all benchmarks

Get a benchmark

Create a benchmark

📘
Blended benchmark compositions

Edit benchmarks

Delete a benchmark

⚠️
Warning

📘
Related

Overview

📘Access requirements

Benchmark types

Resource attributes

Get all benchmarks

Get a benchmark

Create a benchmark

📘Blended benchmark compositions

Edit benchmarks

Delete a benchmark

⚠️Warning

📘Related

📘
Access requirements

📘
Blended benchmark compositions

⚠️
Warning

📘
Related