Benchmark proxies allow entities' estimated returns to be derived from benchmark returns. A benchmark proxy configuration associates an entity with a benchmark starting from a specific date.

Access requirements

All endpoints require the "API Access: Create, edit, and delete" application permission. GET requests require the estimated_performance:read OAuth scope. POST, PATCH, and DELETE requests require the estimated_performance:write OAuth scope.

Resource overview

Benchmark proxies are described by the below attributes.

Get benchmark proxies

Returns benchmark proxies filtered by one or more entity IDs.

GET /v1/benchmark_proxies

• filter[entity_id]: Comma-separated list of entity IDs to filter by (required).
• page[limit]: Maximum number of items to return per page (optional).

Authentication

This endpoint requires a valid API key or OAuth token. Include your credentials in the request header as Authorization: Bearer {token}.

Example

GET https://{firm}.addepar.com/api/v1/benchmark_proxies?filter[entity_id]=12345

{
    "data": [
        {
            "type": "benchmark_proxies",
            "id": "12345_2024-01-15",
            "attributes": {
                "entity_id": 12345,
                "benchmark_id": 789,
                "benchmark_name": "S&P 500",
                "as_of_date": "2024-01-15"
            }
        },
        {
            "type": "benchmark_proxies",
            "id": "12345_2024-06-01",
            "attributes": {
                "entity_id": 12345,
                "benchmark_id": 456,
                "benchmark_name": "Russell 2000",
                "as_of_date": "2024-06-01"
            }
        }
    ]
}

Response codes

• 200 OK -- Success
• 400 Bad Request -- Missing or invalid filter[entity_id] parameter
• 403 Forbidden -- Lacking necessary permissions
• 404 Not Found -- Entity ID is nonexistent or not permissioned

Get a single benchmark proxy

Returns a single benchmark proxy by its composite ID.

GET /v1/benchmark_proxies/:id

• id: The composite ID in format {entityId}_{as_of_date} (e.g., 12345_2024-01-15) (required).

Example

GET https://{firm}.addepar.com/api/v1/benchmark_proxies/12345_2024-01-15

{
    "data": {
        "type": "benchmark_proxies",
        "id": "12345_2024-01-15",
        "attributes": {
            "entity_id": 12345,
            "benchmark_id": 789,
            "benchmark_name": "S&P 500",
            "as_of_date": "2024-01-15"
        }
    }
}

Response codes

• 200 OK -- Success
• 400 Bad Request -- Invalid ID format
• 403 Forbidden -- Lacking necessary permissions
• 404 Not Found -- Benchmark proxy not found or entity not permissioned

Create or update benchmark proxies

Creates or updates benchmark proxies using upsert semantics. If a proxy with the same entity ID and as-of date already exists, it will be updated with the new benchmark ID; otherwise, a new proxy will be created.

POST /v1/benchmark_proxies

Example

POST https://{firm}.addepar.com/api/v1/benchmark_proxies

{
    "data": [
        {
            "type": "benchmark_proxies",
            "attributes": {
                "entity_id": 12345,
                "benchmark_id": 789,
                "as_of_date": "2024-01-15"
            }
        }
    ]
}

{
    "data": [
        {
            "type": "benchmark_proxies",
            "id": "12345_2024-01-15",
            "attributes": {
                "entity_id": 12345,
                "benchmark_id": 789,
                "benchmark_name": "S&P 500",
                "as_of_date": "2024-01-15"
            }
        }
    ]
}

Validation requirements

• The entity_id must reference an existing value-based ValuableEntity
• The benchmark_id must reference an existing benchmark
• No duplicate as-of dates are allowed for the same entity in a single request
• User must have write permissions for estimated returns

Response codes

• 201 Created -- Success
• 400 Bad Request -- Invalid payload, missing required attributes, invalid benchmark ID, invalid entity type, or duplicate as-of dates in request
• 403 Forbidden -- Lacking the required permissions to write estimated returns
• 404 Not Found -- Entity ID or benchmark ID is nonexistent or not permissioned

Update a single benchmark proxy

Updates the benchmark ID for an existing benchmark proxy. Only the benchmark_id attribute can be modified; entity_id and as_of_date are immutable.

PATCH /v1/benchmark_proxies/:id

• id: The composite ID in format {entityId}_{as_of_date} (e.g., 12345_2024-01-15) (required).

Example

PATCH https://{firm}.addepar.com/api/v1/benchmark_proxies/12345_2024-01-15

{
    "data": {
        "type": "benchmark_proxies",
        "id": "12345_2024-01-15",
        "attributes": {
            "benchmark_id": 456
        }
    }
}

{
    "data": {
        "type": "benchmark_proxies",
        "id": "12345_2024-01-15",
        "attributes": {
            "entity_id": 12345,
            "benchmark_id": 456,
            "benchmark_name": "Russell 2000",
            "as_of_date": "2024-01-15"
        }
    }
}

Response codes

• 200 OK -- Success
• 400 Bad Request -- Invalid payload, attempting to modify immutable attributes, or invalid benchmark ID
• 403 Forbidden -- Lacking the required permissions to write estimated returns
• 404 Not Found -- Benchmark proxy not found or entity not permissioned

Delete a single benchmark proxy

Deletes a single benchmark proxy configuration.

DELETE /v1/benchmark_proxies/:id

• id: The composite ID in format {entityId}_{as_of_date} (e.g., 12345_2024-01-15) (required).

Example

DELETE https://{firm}.addepar.com/api/v1/benchmark_proxies/12345_2024-01-15

HTTP/1.1 204 No Content

Response codes

• 204 No Content -- Successfully deleted the benchmark proxy
• 400 Bad Request -- Invalid ID format
• 403 Forbidden -- Lacking the required permissions to write estimated returns
• 404 Not Found -- Benchmark proxy not found or entity not permissioned

Delete all benchmark proxies for an entity

Deletes all benchmark proxy configurations for a specific entity.

DELETE /v1/benchmark_proxies/entity/:entityId

• entityId: The entity ID (integer) (required).

Example

DELETE https://{firm}.addepar.com/api/v1/benchmark_proxies/entity/12345

HTTP/1.1 204 No Content

Response codes

• 204 No Content -- Successfully deleted all benchmark proxies for the entity
• 400 Bad Request -- Invalid entity ID format
• 403 Forbidden -- Lacking the required permissions to write estimated returns
• 404 Not Found -- Entity ID is nonexistent or not permissioned

Related resources

Benchmarks | Benchmark Associations