Benchmarks are standards against which you can measure performance.

Use the Benchmarks API to get, create, update, and delete benchmarks in Addepar. You can also use the Benchmark Compositions API, Imported Benchmark Data API, and Benchmark Associations Strategies API for other benchmark management.


Base route	/v1/benchmarks
Endpoints	GET /v1/benchmarks /v1/benchmarks/:id POST /v1/benchmarks PATCH /v1/benchmarks/:id DELETE /v1/benchmarks/:id
Produces	JSON
Pagination	500
Application permissions required	"API Access: Create, edit, and delete" "Portfolio Access" determines the entities that are accessible. "Benchmark library"
OAuth scopes	`BENCHMARKS_READ` or `BENCHMARKS_WRITE`

Supported benchmarks

Blended benchmarks are composed of multiple benchmarks, which can either be other blended benchmarks or another benchmark type. Each underlying benchmark is assigned a weight that determines how it contributes to the total return. Example: 50% equity benchmark / 50% fixed income benchmark
Imported benchmarks consist of daily returns provided by a firm because their custom benchmarks aren't available from other sources.
Fixed return benchmarks have a fixed annual return. A 20.00% fixed return benchmark will show 20% annually year-over-year.
Security benchmarks are based on the performance of a specific investment.
Portfolio benchmarks are based on the performance of a specific portfolio.

Index benchmarks are provided by vendors and therefore can't be created via the API. You can only update an index benchmark's display name via the API.

Resource overview

Benchmarks are described by the below resource object attributes. Attributes required for creating benchmarks are noted.

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

Attribute	Description	Example
`id`	Identifies a specific benchmark. Number.	`524`
`benchmark_type`	Classification to differentiate benchmarks based on their data source and composition. String. Possible values are: - `"blended"` - `"imported"` - `"fixed_return"` - `"portfolio_benchmark"` - `"security_benchmark"`See "Supported benchmarks" for details about each type.	`"fixed_return"`
`rebalance_interval`	Frequency with which the benchmark is rebalanced. String. Possible values are: - `None`: No rebalancing - `ONE_DAY`: Daily - `ONE_WEEK`: Weekly - `ONE_MONTH`: Monthly - `THREE_MONTHS`: Quarterly - `SIX_MONTHS`: Semi-annually - `ONE_YEAR`: AnnuallyOnly required for blended benchmarks.	`"THREE_MONTHS"`
`fixed_return`	A fixed-value annual return percentage. Number. Only required for fixed return benchmarks.	`0.15`(represents 15%)
`is_compounded`	Indicates whether the fixed annual return is compounded. Boolean. Only required for fixed return benchmarks.	`true`
`vendor_id`	Indicates the ID used by the vendor that corresponds to this particular index. This field is immutable. Number. Only required for index benchmarks.	`4118`
`index_type`	Type of index. This field is immutable. String. Possible values are: - `"Index Return"` - `"Index Return (Estimated)"` - `"Index Return (Preliminary)"` - `"Total Return"` - `"Net Return"` - `"Hedged Return"` - `"Total Return - MTD"`Only required for index benchmarks.	`"Total Return"`
`index_name`	While the index display name can be updated, this field contains the original name of the index. This field is immutable. String. Only required for index benchmarks.	`"tr USNTBIROR"`
`start_date`	The earliest date for which there is returns data. String. "YYYY-MM-DD" Only required for index benchmarks.	`2022-12-31`
`end_date`	The most recent date for which there is returns data. String. "YYYY-MM-DD" Only required for index benchmarks.	`2024-01-30`
`benchmark_composition_id`	Links to the underlying composition of the benchmark. Only applies to blended benchmarks.	`571`
`entity_id`	The Entity ID corresponding to an existing entity that will be the basis of the benchmark. Only applies to security and portfolio benchmarks. For security benchmarks, this entity must be an investment. For portfolio benchmarks, must be one of the below entity types: - Household - Client - Holding Company - Trust - Fund - Holding Account - Managed Fund - Sleeve	`14219`

Create a benchmark

Adds a new benchmark to your firm.

Note that index benchmarks can't be created via the API. If you are looking to add a new index benchmark to your firm's environment, please reach out to your Addepar contact.

POST /v1/benchmarks

Required fields for all benchmark types

benchmark_type
name: The benchmark's display name. This field is required for all types except fixed_return.

Create a blended benchmark

Required fields

blended: A JSON object containing a rebalance_interval field
rebalance_interval: Indicates how often the benchmark composition will be rebalanced. Possible values are:
- None: No rebalancing
- ONE_DAY: Daily
- ONE_WEEK: Weekly
- ONE_MONTH: Monthly
- THREE_MONTHS: Quarterly
- SIX_MONTHS: Semi-annually
- ONE_YEAR: Annually

Other fields
benchmark_composition_id: This field does not need to be included in POST or PATCH requests and will always be the same as the ID of the benchmark itself. It can be used with the /v1/benchmark_compositions/:id endpoint to access the underlying composition of the blended benchmark.

Example

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

{
    "data": [ 
        {
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "blended",
                "name": "blended test",
                "blended": {
                    "rebalance_interval": "one_day"
                }
            }
        }
    ]
}

HTTP/1.1 200 Success

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

Response codes

200 OK: Success.
400 Bad Request: Invalid request payload.
403 Unauthorized: The current user does not have permission to create/update benchmarks.
409 Conflict: There is already an existing benchmark with the same name.

Create an imported benchmark

There are no required fields specific to imported benchmarks.

The /v1/imported_benchmark_data/:id endpoints are used to retrieve/update the imported returns for an imported benchmark.

Example

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

{
    "data": [ 
        {
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "imported",
                "name": "imported test"
            }
        }
    ]
}

Create a fixed return benchmark

Required fields

fixed_return: A JSON object containing the below fields:
- fixed_return: A decimal corresponding to the desired annual rate of return. To create a 5% fixed return benchmark, set this field to 0.05. Up to 17 decimal places are supported.
- is_compounded: A true/false value indicating whether the returns should be compounded.

Note: The name field is not required for fixed return benchmarks. The benchmark name will be based on the fixed_return and is_compounded fields. For example, if fixed_return is 0.05 and is_compounded is true, then the name will be 5.00 % Compounded. Providing a value for name will not cause an error, but the name will still follow the above convention.

Example

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

{
    "data": [ 
        {
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "fixed_return",
                "fixed_return": {
                    "fixed_return": 0.15,
                    "is_compounded": true
                },
                "name": "fixed_return test"
            }
        }
    ]
}

Create a portfolio benchmark

Required fields

portfolio: A JSON object containing the below field:
- entity_id: The ID of the entity that the benchmark is based on. For portfolio benchmarks, this entity must be one of the below model types:
  - Holding Account
  - Fund
  - Holding Company
  - Managed Fund
  - Client
  - Sleeve
  - Trust

Example

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

{
    "data": [ 
        {
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "portfolio_benchmark",
                "name": "portfolio test",
                "portfolio": {
                    "entity_id": 123
                }
            }
        }
    ]
}

Create a security benchmark

Required fields

security: A JSON object with the below field:
- entity_id: The ID of the entity that the benchmark is based on. For security benchmarks, this entity must be one of the below model types:
  - Custom Asset
  - Money Market Fund
  - Bond
  - CMO
  - Certificate of Deposit
  - Closed End Fund
  - Convertible Note
  - ETF
  - ETN
  - Master Limited Partnership
  - Mutual Fund
  - Option
  - Stock
  - REIT
  - Preferred Stock
  - UIT
  - Warrant
  - Forward Contract
  - Digital Asset
  - Historical Segment

Example

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

{
    "data": [ 
        {
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "security_benchmark",
                "name": "security test",
                "security": {
                    "entity_id": 123
                }
            }
        }
    ]
}

Get all benchmarks

Returns a paginated list of all active benchmarks. The default pagination limit is 500.

GET /v1/benchmarks

Example

GET https://examplefirm.addepar.com/api/v1/benchmarks

{
    "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": "570",
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "INDEX",
                "name": "tr S&P600I (Total Return)",
                "index": {
                    "vendor": "tr",
                    "vendor_id": "S&P600I",
                    "index_type": "TOTAL_RETURN",
                    "index_name": "tr S&P600I",
                    "start_date": null,
                    "end_date": null
                }
            },
            "links": {
                "self": "/v1/benchmarks/570"
            }
        },
        {
            "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"
            }
        },
        {
            "id": "734",
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "IMPORTED",
                "name": "Imported Benchmark 1"
            },
            "links": {
                "self": "/v1/benchmarks/734"
            }
        },
        {
            "id": "735",
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "IMPORTED",
                "name": "Imported Benchmark 2"
            },
            "links": {
                "self": "/v1/benchmarks/735"
            }
        }
    ],
    "included": [],
    "links": {
        "prev": null,
        "next": null
    }
}

Response codes

200 OK: Success

Get a benchmark

Returns a benchmark with the given ID.

GET /v1/benchmarks/:id

Example

GET https://examplefirm.addepar.com/api/v1/benchmarks/571

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

Response codes

200 OK: Success
404 Not Found: No benchmark exists corresponding to the provided ID.

Update a benchmark

Modifies an existing benchmark.

PATCH /v1/benchmarks/:id

Fields that can't be updated

benchmark_type
Blended Benchmarks:
- benchmark_composition_id
Portfolio and Security Benchmarks:
- entity_id
Index Benchmarks:
- vendor
- vendor_id
- index_type
- index_name
- start_date
- end_date

The only field that can be updated on an index benchmark is name. All its other fields are immutable.

Example

PATCH https://examplefirm.addepar.com/api/v1/benchmarks/739

{
    "data": {
        "id": "739",
        "type": "benchmarks",
        "attributes": {
            "benchmark_type": "FIXED_RETURN",
            "name": "15.00 %",
            "fixed_return": {
                "fixed_return": 0.15,
                "is_compounded": false
            }
        }
    }
}

{
    "data": {
        "id": "739",
        "type": "benchmarks",
        "attributes": {
            "benchmark_type": "FIXED_RETURN",
            "name": "new name",
            "fixed_return": {
                "fixed_return": 0.17,
                "is_compounded": false
            }
        },
        "links": {
            "self": "/v1/benchmarks/739"
        }
    },
    "included": []
}

Response codes

200 OK: Success
400 Bad Request: Invalid request payload.
403 Unauthorized: The current user does not have permission to update benchmarks.
404 Not Found: No benchmark exists corresponding to the provided ID.
409 Conflict: There is already an existing benchmark with the same name.

Update multiple benchmarks

Modify multiple existing benchmarks in bulk.

PATCH /v1/benchmarks/:id

Example

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

{
    "data": [
        {
            "id": "739",
            "type": "benchmarks",
            "attributes": {
                "name": "name",
                "fixed_return": {
                    "fixed_return": 0.17,
                    "is_compounded": true
                }
            }
        },
        {
            "id": "571",
            "type": "benchmarks",
            "attributes": {
                "blended": {
                    "rebalance_interval": "six_months"
                }
            }
        }
    ]
}

{
    "data": [
        {
            "id": "739",
            "type": "benchmarks",
            "attributes": {
                "benchmark_type": "FIXED_RETURN",
                "name": "17.00 % Compounded",
                "fixed_return": {
                    "fixed_return": 0.17,
                    "is_compounded": true
                }
            },
            "links": {
                "self": "/v1/benchmarks/739"
            }
        },
        {
            "id": "571",
            "type": "benchmarks",
            "attributes": {
                "blended": {
                    "rebalance_interval": "SIX_MONTHS",
                    "benchmark_composition_id": 571
                },
                "benchmark_type": "BLENDED",
                "name": "blended test"
            },
            "links": {
                "self": "/v1/benchmarks/571"
            }
        }
    ],
    "included": [],
    "links": {
        "prev": null,
        "next": null
    }
}

Response codes

200 OK: Success
400 Bad Request: Invalid request payload.
403 Unauthorized: The current user does not have permission to update benchmarks.
404 Not Found: No benchmark exists corresponding to the provided ID.
409 Conflict: There is already an existing benchmark with the same name.

Delete a benchmark

Deletes a user-created benchmark if it exists. Deleting benchmarks is typically not recommended due to the potential for breaking downstream relationships and usage.

Fixed return and index benchmarks cannot be deleted.

DELETE /v1/benchmarks/:id

Example

DELETE https://examplefirm.addepar.com/api/v1/benchmarks/571

HTTP/1.1 204 No Content

Response codes

204 No Content: Benchmark was successfully deleted.
400 Bad Request: Attempt to delete a benchmark that cannot be deleted.
403 Unauthorized: The current user does not have permission to delete benchmarks.
404 Not Found: No benchmark exists corresponding to the provided ID.