Benchmark Associations Strategies
A benchmark associations strategy is a list of benchmark associations that map attribute values to the benchmark(s) that should be applied to entities with those attribute values.
Use the Benchmark Associations Strategies API to manage these strategies. For general benchmark management, use the Benchmarks API.
| Base route | /v1/benchmark_associations_strategies |
| Endpoints | GET /v1/benchmark_associations_strategies /v1/benchmark_associations_strategies/:id POST /v1/benchmark_associations_strategies PATCH /v1/benchmark_associations_strategies/:id DELETE /v1/benchmark_associations_strategies/:id |
| Produces | JSON |
| Pagination | 500 strategies |
| Application permissions required | "API Access: Create, edit, and delete" "Benchmark associations" |
| OAuth scopes | BENCHMARKS_READ or BENCHMARKS_WRITE |
Resource overview
Benchmark associations strategies are described by the below properties.
| Property | Description | Example |
|---|---|---|
id | Identifies the associations strategy. Number. | 11 |
display_name | The associations strategy's name that is displayed to the user. Doesn't have to be unique. String. | "Security Benchmarks" |
matching_type | Indicates where associations will be applied. Possible values are: - PATH: Assign benchmarks to all positions matching your association rules. Rolls up to groupings. This is referred to as positions in Addepar.- PDN: Assign independent benchmarks to specific rows. Doesn't roll up. This is referred to as table rows in Addepar. When using this matching, each association can only have one rule. | PATH |
benchmark_associations | A list of benchmark associations objects, which each consist of benchmarks and rules.The order of the associations in the list will determine the order in which association rules are applied. | See example below |
benchmarks | A list of existing benchmark IDs to be associated. Portfolio benchmarks can't be used in benchmark associations. | See example below |
rules | Represents an attribute value that determines which entities will have the benchmark assigned. Consists of attribute, type, and value. | See example below |
attribute | API field name of the desired attribute. Only "Word" attributes and some "Other" attributes that have an entity value (more details below) can be used. | asset_class |
type | The attribute's value type. Possible values types are: - WORD- FINANCIAL_ENTITYRequired for GET requests. | WORD |
value | Attribute value that will be used in the association. Usually, this is a string. However, "Other" attributes with an entity value should provide its Entity ID as either a number or a numeric string. | "Equity" |
Using attributes with entity values
In addition to all "Word" attributes, three built-in "Other" attributes have entity values and can be used in benchmark associations:
bottom_level_holding_account: Provide an account's Entity ID as the value.sleeve: Provide a sleeve's Entity ID as the value.security: Provide an investment's Entity ID as the value.
If the provided Entity ID belongs to an entity with the incorrect model type for the given attribute, a 400 error will occur.
Example JSON
{
"data": {
"id": "11",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "security",
"value": 200,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/11"
}
},
"included": []
}
Get all benchmark associations strategies
Returns a paginated list of all active benchmark associations strategies.
GET /v1/benchmark_associations_strategies
Optional pagination parameters
A 500 strategy per page maximum is enforced per request. If there are more than 500, the set will be truncated automatically, and the remaining values linked from the "next" URL in the top-level links object. "next": /v1/benchmark_associations_strategies?page[limit]=500&page[after]=500
page[limit]: Number of strategies to be returned. Integer. The maximum result set size is 500.page[after]: The next page; the returned paginated data must have as its first item the item that is immediately after the cursor in the results list. Integer.
Example
GET https://examplefirm.addepar.com/api/v1/benchmark_associations_strategies
HTTP/1.1 200 Success
{
"data": [
{
"id": "2",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "asset_class",
"value": "Equity",
"type": "WORD"
}
],
"benchmarks": [
734
]
},
{
"rules": [
{
"attribute": "sector",
"value": "Energy",
"type": "WORD"
}
],
"benchmarks": [
735
]
}
],
"display_name": "Default Strategy"
},
"links": {
"self": "/v1/benchmark_associations_strategies/2"
}
},
{
"id": "3",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PDN",
"benchmark_associations": [
{
"rules": [
{
"attribute": "asset_class",
"value": "Derivative",
"type": "WORD"
}
],
"benchmarks": [
734
]
},
{
"rules": [
{
"attribute": "country",
"value": "AFG",
"type": "WORD"
}
],
"benchmarks": [
559
]
}
],
"display_name": "PDN Strategy"
},
"links": {
"self": "/v1/benchmark_associations_strategies/3"
}
},
{
"id": "4",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/4"
}
},
{
"id": "5",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/5"
}
},
{
"id": "6",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "bottom_level_holding_account",
"value": 22,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/6"
}
},
{
"id": "7",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "bottom_level_holding_account",
"value": 22,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/7"
}
},
{
"id": "8",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "bottom_level_holding_account",
"value": 208,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/8"
}
},
{
"id": "9",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "bottom_level_holding_account",
"value": 208,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/9"
}
},
{
"id": "10",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "security",
"value": 213,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/10"
}
},
{
"id": "11",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "security",
"value": 200,
"type": "FINANCIAL_ENTITY"
}
],
"benchmarks": [
571
]
}
],
"display_name": "(ALL) Security Benchmarks"
},
"links": {
"self": "/v1/benchmark_associations_strategies/11"
}
}
],
"included": [],
"links": {
"prev": null,
"next": null
}
}
Response codes
200 OK: Success.403 Forbidden: The currently logged-in user does not have permission to view/edit benchmark associations.
Get a benchmark associations strategy
Returns a benchmark associations strategy with the given ID.
GET /v1/benchmark_associations_strategies/:id
Example
GET https://examplefirm.addepar.com/api/v1/benchmark_associations_strategies/2
HTTP/1.1 200 Success
{
"data": {
"id": "2",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "asset_class",
"value": "Equity",
"type": "WORD"
}
],
"benchmarks": [
734
]
},
{
"rules": [
{
"attribute": "sector",
"value": "Energy",
"type": "WORD"
}
],
"benchmarks": [
735
]
}
],
"display_name": "Default Strategy"
},
"links": {
"self": "/v1/benchmark_associations_strategies/2"
}
},
"included": []
}
Response codes
200 OK: Success.403 Forbidden: The currently logged-in user does not have permission to view/edit benchmark associations.404 Not Found: The provided ID does not exist.
Create a benchmark associations strategy
Adds a new benchmark associations strategy to your firm. Only one strategy can be created per request.
POST /v1/benchmark_associations_strategies
Example
POST https://examplefirm.addepar.com/api/v1/benchmark_associations_strategies
{
"data": {
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "asset_class",
"value": "Equity"
}
],
"benchmarks": [
571
]
}
],
"display_name": "Equity Strategy"
}
}
}
HTTP/1.1 201 Created
{
"data": {
"id": "18",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [
{
"rules": [
{
"attribute": "asset_class",
"value": "Equity",
"type": "WORD"
}
],
"benchmarks": [
571
]
}
],
"display_name": "Equity Strategy"
},
"links": {
"self": "/v1/benchmark_associations_strategies/18"
}
},
"included": []
}
Response codes
201 Created: Success.400 Bad Request: Invalid payload403 Forbidden: The currently logged-in user does not have permission to view/edit benchmark associations.
Update a benchmark associations strategy
Modifies an existing benchmark associations strategy.
PATCH /v1/benchmark_associations_strategies/:id
To update the matching_type and/or display_name of the strategy without changing the underlying associations, omit the benchmark_associations field from the request. This will preserve all existing associations.
When you include the benchmark_associations, newly provided associations will overwrite all existing associations. To append new associations to the existing list, run a GET /v1/benchmark_associations_strategies/:id request first and modify the payload as desired.
Example
PATCH https://examplefirm.addepar.com/api/v1/benchmark_associations_strategies/18
{
"data": {
"id": "18",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": null,
"display_name": "Equity Strategy"
}
}
}
HTTP/1.1 200 Success
{
"data": {
"id": "18",
"type": "benchmark_associations_strategies",
"attributes": {
"matching_type": "PATH",
"benchmark_associations": [],
"display_name": "Equity Strategy"
},
"links": {
"self": "/v1/benchmark_associations_strategies/18"
}
},
"included": []
}
Response codes
200 OK: Success.400 Bad Request: Invalid payload403 Forbidden: The currently logged-in user does not have permission to view/edit benchmark associations.404 Not Found: The provided ID does not exist.409 Conflict: The id field in the request payload does not match the ID in the URL.
Delete a benchmark associations strategy
Deletes an existing benchmark associations strategy if it exists.
DELETE /v1/benchmark_associations_strategies/:id
Example
DELETE https://examplefirm.addepar.com/api/v1/benchmark_associations_strategies/18
HTTP/1.1 204 No Content
Response codes
204 No Content: Success.403 Forbidden: The currently logged-in user does not have permission to view/edit benchmark associations.404 Not Found: The provided ID does not exist.
Updated 4 months ago