Benchmark Compositions

A benchmark composition defines the weighted components of a blended benchmark. Each composition contains one or more intervals, allowing allocations to change over time. Every composition shares its ID with the blended benchmark it belongs to.

Use this API to retrieve or update compositions. To manage the parent benchmark itself, use the Benchmarks API.

Overview

📘

Access requirements

• "API Access: Create, edit, and delete"
• "Benchmark library"

Resource structure

A composition is an array of intervals. Each interval represents the allocation for a date range.

Get all compositions

Returns a paginated list of all benchmark compositions.

GET /v1/benchmark_compositions

curl -X GET "https://{firm}.addepar.com/api/v1/benchmark_compositions" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1"

{
  "data": [
    {
      "id": "571",
      "type": "benchmark_compositions",
      "attributes": {
        "intervals": [
          {
            "date": null,
            "value": [
              { "benchmark_id": 421, "percent": 0.5 },
              { "benchmark_id": 734, "percent": 0.5 }
            ]
          }
        ]
      },
      "links": { "self": "/v1/benchmark_compositions/571" }
    }
  ],
  "included": [],
  "links": { "prev": null, "next": null }
}

Response codes:

• 200 OK -- Success

Get a composition

Returns a single composition by ID.

GET /v1/benchmark_compositions/:id

Response codes:

• 200 OK -- Success
• 404 Not Found -- No blended benchmark exists with this ID

Update a composition

Replaces or adds intervals in an existing composition. Existing intervals not included in the request are preserved.

PATCH /v1/benchmark_compositions/:id

Rules:

• Every valid composition must include one interval with "date": null (the initial allocation).
• If the request includes an interval with the same date as an existing one, it overwrites that interval.
• To remove an interval, set its value to null.
• A benchmark cannot appear more than once within a single interval.
• If the request contains multiple intervals with the same date, they are merged into one interval (component lists concatenated).

curl -X PATCH "https://{firm}.addepar.com/api/v1/benchmark_compositions/736" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -d '{
    "data": {
      "id": "736",
      "type": "benchmark_compositions",
      "attributes": {
        "intervals": [
          {
            "date": null,
            "value": [
              { "benchmark_id": 734, "percent": 0.5 },
              { "benchmark_id": 421, "percent": 0.3 },
              { "benchmark_id": 735, "percent": 0.2 }
            ]
          },
          {
            "date": "2024-07-01",
            "value": [
              { "benchmark_id": 734, "percent": 0.6 },
              { "benchmark_id": 421, "percent": 0.4 }
            ]
          },
          {
            "date": "2020-12-31",
            "value": null
          }
        ]
      }
    }
  }'

This request:

1. Overwrites the initial allocation (3 components).
2. Adds a new interval starting 2024-07-01 (2 components).
3. Removes the interval that previously started on 2020-12-31.

Response codes:

• 200 OK -- Composition updated
• 400 Bad Request -- Invalid payload (duplicate benchmark in interval, missing null-date interval)
• 403 Forbidden -- No permission to update benchmarks
• 404 Not Found -- No blended benchmark exists with this ID
• 409 Conflict -- ID in URL does not match ID in request body

📘

Related

• Benchmarks -- Create and manage the parent benchmark resource
• Benchmark Associations Strategies -- Link benchmarks to portfolio strategies
• Imported Benchmark Data -- Daily returns for imported benchmarks