Benchmark Compositions (Beta)
A benchmark composition is a list of weighted benchmarks. Every benchmark composition is linked to one blended benchmark, as it represents the composition for that benchmark. A composition may contain multiple intervals, allowing the value of a benchmark composition to change over time.
Use the Benchmark Compositions API to retrieve or update benchmark compositions. To manage a blended benchmark as a whole, use the Benchmarks API.
Beta Feature
The base route /v1/benchmark_compositions 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/benchmark_compositions |
| Endpoints | GET /v1/benchmark_compositions /v1/benchmark_compositions/id PATCH /v1/benchmark_compositions/id |
| Produces | JSON |
| Pagination | 500 |
| Application permissions required | "API Access: Create, edit, and delete" "Benchmark library" |
| OAuth scopes | BENCHMARKS_READ or BENCHMARKS_WRITE |
Resource overview
| Attribute | Description | Example |
|---|---|---|
date | Date the interval started. At least one interval must have a date of null, representing the initial value. If there are multiple intervals with the same date, they will be aggregated into a single interval. String."YYYY-MM-DD" Date is required for every interval. | "2023-31-12" |
value | Field that lists benchmark exposure objects. Object. Value is required for every interval. | See examples below |
benchmark_id | Identifies the benchmark composition. A benchmark composition has the same ID as the blended benchmark it's associated with. A benchmark can only appear once in an interval. Portfolio benchmarks aren't allowed in blended benchmarks. Number. Benchmark ID is required for every value. | 571 |
percent | Value's portion of a composition. The sum of percents in a benchmark composition don't need to add up to 100%. Percents can also be negative, which represents inverse exposure. Percent is required for every value. | 0.1 |
Get all benchmark compositions
Returns a paginated list of all active benchmark compositions. The default pagination limit is 500.
GET /v1/benchmark_compositions
Example
GET https://examplefirm.addepar.com/api/v1/benchmark_compositions
HTTP/1.1 200 Success
{
"data": [
{
"id": "571",
"type": "benchmark_compositions",
"attributes": {
"intervals": [
{
"date": null,
"value": [
{
"benchmark_id": 421,
"percent": 0.5
},
{
"benchmark_id": 734,
"percent": 0.5
},
{
"benchmark_id": 735,
"percent": 0.5
}
],
"weight": 1.0
}
]
},
"links": {
"self": "/v1/benchmark_compositions/571"
}
},
{
"id": "736",
"type": "benchmark_compositions",
"attributes": {
"intervals": [
{
"date": null,
"value": [
{
"benchmark_id": 421,
"percent": 0.5
},
{
"benchmark_id": 734,
"percent": 0.5
}
],
"weight": 1.0
}
]
},
"links": {
"self": "/v1/benchmark_compositions/736"
}
}
],
"included": [],
"links": {
"prev": null,
"next": null
}
}
Response codes
200 OK: Success.
Get a benchmark composition
Returns a benchmark composition with the given ID.
GET /v1/benchmark_compositions/id
Example
GET https://examplefirm.addepar.com/api/v1/benchmark_compositions/571
HTTP/1.1 200 Success
{
"data": {
"id": "571",
"type": "benchmark_compositions",
"attributes": {
"intervals": [
{
"date": null,
"value": [
{
"benchmark_id": 734,
"percent": 0.5
},
{
"benchmark_id": 421,
"percent": 0.5
}
],
"weight": 1.0
}
]
},
"links": {
"self": "/v1/benchmark_compositions/571"
}
},
"included": []
}
Response codes
200 OK: Success404 Not Found: The provided ID does not correspond to an existing blended benchmark.
Update a benchmark composition
Modifies the underlying composition of an existing blended benchmark.
PATCH /v1/benchmark_compositions/id
Important notes
- These requests preserve existing data where possible. If the request payload includes an interval with the same date as an existing interval, the existing interval will be overwritten.
- The same benchmark can't be included more than once in a given interval.
- Every valid benchmark composition must include an interval with
"date": null, which corresponds to the initial value of the composition. - To remove an existing interval from a composition, users must explicitly set the value field to
null. As an example, to remove an existing interval that begins on 12/31/2020, the payload must include:
{
"date": "2020-12-31",
"value": null
}
- If the request includes multiple interval JSONs with the same date, they will be concatenated into a single interval in the response. For example, a request may contain two intervals for 12/31/2020, as shown below:
{
"intervals": [
{
"date": "2020-12-31",
"value": [
{
"benchmark_id": 123,
"percent": 0.5
}
]
},
{
"date": "2020-12-31",
"value": [
{
"benchmark_id": 456,
"percent": 0.5
}
]
}
]
}
These would be joined into a single interval:
{
"date": null,
"value": [
{
"benchmark_id": 456,
"percent": 0.5
},
{
"benchmark_id": 123,
"percent": 0.5
}
]
}
Example
PATCH https://examplefirm.addepar.com/api/v1/benchmark_compositions
{
"data": {
"id": "736",
"type": "benchmark_compositions",
"attributes": {
"intervals": [
{
"date": null,
"value": [
{
"benchmark_id": 734,
"percent": 0.5
},
{
"benchmark_id": 421,
"percent": 0.5
},
{
"benchmark_id": 735,
"percent": 0.5
},
{
"benchmark_id": 571,
"percent": 0.5
}
]
},
{
"date": "2020-12-31",
"value": null
}
]
}
}
}
HTTP/1.1 200 Success
Response codes
200 OK: The composition was updated successfully.400 Bad Request: Request payload is improperly formatted or contains invalid data.403 Forbidden: The current user does not have permission to update benchmarks.404 Not Found: The provided ID does not correspond to an existing blended benchmark.409 Conflict: There is a mismatch between the id parameter in the URL and the id provided in the request payload.
Updated 3 months ago