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
EndpointsGET
/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
ProducesJSON
Pagination500 strategies
Application permissions required"API Access: Create, edit, and delete"

"Benchmark associations"
OAuth scopesBENCHMARKS_READ or BENCHMARKS_WRITE

Resource overview

Benchmark associations strategies are described by the below properties.

PropertyDescriptionExample
idIdentifies the associations strategy. Number.11
display_nameThe associations strategy's name that is displayed to the user. Doesn't have to be unique. String."Security Benchmarks"
matching_typeIndicates 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_associationsA 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
benchmarksA list of existing benchmark IDs to be associated. Portfolio benchmarks can't be used in benchmark associations.See example below
rulesRepresents an attribute value that determines which entities will have the benchmark assigned. Consists of attribute, type, and value.See example below
attributeAPI 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
typeThe attribute's value type.

Possible values types are:

- WORD
- FINANCIAL_ENTITYRequired for GET requests.
WORD
valueAttribute 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 payload
  • 403 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 payload
  • 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.
  • 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.