Underlying Assets

This route provides access to underlying assets used in derivatives modeling, allowing you to create, retrieve, update, and delete underlying asset records along with their spot values.


Base route	`/v1/derivatives/underlying_assets`
Endpoints	`GET /v1/derivatives/underlying_assets/:id`
Produces	JSON
Pagination	Offset-based (`page[after]`, `page[limit]`)
Application permissions required	Derivatives
OAuth scopes	`derivatives`

📘 Access requirements

To use the Underlying Assets API, your application must have the Derivatives permission enabled. Contact your Addepar representative if you need access.

Resource attributes

Attribute	Description
`entity_name`	String. The name of the underlying entity. Example: `"corporate bond"`
`entity_type`	String. The type of entity. Possible values: `SECURITY`. Example: `"SECURITY"`
`underlying_type`	String. The type of underlying value tracked. Possible values: `PRICE`. Example: `"PRICE"`
`base_currency`	String. ISO 4217 currency code. Example: `"USD"`
`financial_graph_node_id`	Integer. Optional. The ID of the financial graph node linked to this asset. Example: `789`
`metric_values`	Object. Optional. A map of ISO 8601 dates to numeric spot values. Example: `{"2025-01-01": 4.0, "2025-01-02": 5.0}`

Get underlying asset by ID

GET /v1/derivatives/underlying_assets/:id

Retrieves an underlying asset by ID.

📘 Authentication

This endpoint requires a valid API key or OAuth token with the derivatives scope. Pass credentials via the Authorization header.

Query parameters

Parameter	Description
`metric_date_from`	String. Optional. Start date (inclusive) for returning the asset's spot values. ISO 8601 extended format. If omitted, no spot values are returned.
`metric_date_to`	String. Optional. End date (inclusive) for returning the asset's spot values. ISO 8601 extended format. If omitted, no spot values are returned.

Example request

curl -X GET "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/1234?metric_date_from=2025-01-01&metric_date_to=2025-01-31" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/vnd.api+json"

Response codes

200 OK -- Success
403 Forbidden -- Not permitted to make the request
404 Not Found -- An entity with the given ID is not available to the requester

Example response

{
  "data": {
    "id": "1234",
    "type": "derivatives_underlying_assets",
    "attributes": {
      "entity_name": "corporate bond",
      "entity_type": "SECURITY",
      "underlying_type": "PRICE",
      "base_currency": "USD",
      "metric_values": {
        "2025-01-01": 4.0,
        "2025-01-02": 5.0,
        "2025-01-03": 6.0
      }
    },
    "links": {
      "self": "/v1/derivatives_underlying_assets/1234"
    }
  }
}

Get all underlying assets

GET /v1/derivatives/underlying_assets

Retrieves a page of underlying assets.

Query parameters

Parameter	Description
`page[after]`	Integer. Optional. How many entities to skip before starting to return assets. Defaults to 0.
`page[limit]`	Integer. Optional. How many assets to return, at most. Defaults to the server-side maximum.
`metric_date_from`	String. Optional. Start date (inclusive) for returning the entities' spot values. ISO 8601 extended format. If omitted, no spot values are returned.
`metric_date_to`	String. Optional. End date (inclusive) for returning the entities' spot values. ISO 8601 extended format. If omitted, no spot values are returned.

Note that a high page limit with a large window for spot values may result in a large response.

Example request

curl -X GET "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets?metric_date_from=2025-01-01&metric_date_to=2025-01-31" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/vnd.api+json"

Response codes

200 OK -- Success
403 Forbidden -- Not permitted to make the request

Example response

{
  "data": [
    {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "USD",
        "metric_values": {
          "2025-01-01": 4.0,
          "2025-01-02": 5.0,
          "2025-01-03": 6.0
        }
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1234"
      }
    },
    {
      "id": "1235",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some other stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "USD",
        "metric_values": {
          "2025-01-01": 2.3,
          "2025-01-02": 2.4,
          "2025-01-03": 2.5
        }
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1235"
      }
    }
  ]
}

Create underlying assets

POST /v1/derivatives/underlying_assets

Creates one or many underlying assets. Do not provide an id because that field will be assigned by the server.

Example request (single entity)

curl -X POST "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "my underlying stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "USD",
        "financial_graph_node_id": 789,
        "metric_values": {
          "2025-01-01": 4.0,
          "2025-01-02": 5.0,
          "2025-01-03": 6.0
        }
      }
    }
  }'

Example request (multiple entities)

{
  "data": [
    {
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "GBP",
        "metric_values": {
          "2025-01-01": 4.0,
          "2025-01-02": 5.0,
          "2025-01-03": 6.0
        }
      }
    },
    {
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some other stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "GBP",
        "metric_values": {
          "2025-01-01": 2.3,
          "2025-01-02": 2.4,
          "2025-01-03": 2.5
        }
      }
    }
  ]
}

Response codes

201 Created -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- Not permitted to make the request

Example response (single entity)

{
  "data": {
    "id": "1234",
    "type": "derivatives_underlying_assets",
    "attributes": {
      "entity_name": "my underlying stock",
      "entity_type": "SECURITY",
      "underlying_type": "PRICE",
      "base_currency": "USD",
      "financial_graph_node_id": 789,
      "metric_values": {
        "2025-01-01": 4.0,
        "2025-01-02": 5.0,
        "2025-01-03": 6.0
      }
    },
    "links": {
      "self": "/v1/derivatives_underlying_assets/1234"
    }
  }
}

Example response (multiple entities)

{
  "data": [
    {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "GBP",
        "metric_values": {
          "2025-01-01": 4.0,
          "2025-01-02": 5.0,
          "2025-01-03": 6.0
        }
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1234"
      }
    },
    {
      "id": "1235",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "some other stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "GBP",
        "metric_values": {
          "2025-01-01": 2.3,
          "2025-01-02": 2.4,
          "2025-01-03": 2.5
        }
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1235"
      }
    }
  ]
}

Patching underlying assets

When patches are presented for underlying assets, required attributes may be omitted: they are filled in with their previous values.

metric_values is a special case of an optional attribute because of its object value. If the attribute is wholly omitted then the entity's spot values are unchanged. If included then the patch applies to the inclusive interval from the earliest given date to the latest:

Spot values outside the interval remain unchanged.
Spot values patched as null instead of as a number are deleted.
Spot values within the interval are provided in the response to confirm the result of the patch.

Patch underlying asset by ID

PATCH /v1/derivatives/underlying_assets/:id

Modifies an underlying asset.

Example request

curl -X PATCH "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/1234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "my stock",
        "entity_type": "SECURITY",
        "base_currency": "USD",
        "metric_values": {
          "2025-01-01": 7.0,
          "2025-01-02": null,
          "2025-01-04": 8.0
        }
      }
    }
  }'

Response codes

200 OK -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- Not permitted to make the request
404 Not Found -- An entity with the given ID is not available to the requester
409 Conflict -- ID in path does not match ID in payload

Example response

{
  "data": {
    "id": "1234",
    "type": "derivatives_underlying_assets",
    "attributes": {
      "entity_name": "my stock",
      "entity_type": "SECURITY",
      "underlying_type": "PRICE",
      "base_currency": "USD",
      "metric_values": {
        "2025-01-01": 7.0,
        "2025-01-03": 6.0,
        "2025-01-04": 8.0
      }
    },
    "links": {
      "self": "/v1/derivatives_underlying_assets/1234"
    }
  }
}

Patch underlying assets

PATCH /v1/derivatives/underlying_assets

Modifies one or many underlying assets.

Example request (single entity)

{
  "data": {
    "id": "1234",
    "type": "derivatives_underlying_assets",
    "attributes": {
      "entity_name": "my stock",
      "entity_type": "SECURITY",
      "base_currency": "USD",
      "metric_values": {
        "2025-01-01": 7.0,
        "2025-01-02": null,
        "2025-01-04": 8.0
      }
    }
  }
}

Example request (multiple entities)

{
  "data": [
    {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "stock patched",
        "entity_type": "SECURITY",
        "base_currency": "USD"
      }
    },
    {
      "id": "1235",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "bond patched",
        "entity_type": "SECURITY",
        "base_currency": "GBP"
      }
    }
  ]
}

Response codes

200 OK -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- Not permitted to make the request
404 Not Found -- An entity with the given ID is not available to the requester

Example response (single entity)

{
  "data": [
    {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "my stock",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "USD",
        "metric_values": {
          "2025-01-01": 7.0,
          "2025-01-03": 6.0,
          "2025-01-04": 8.0
        }
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1234"
      }
    }
  ]
}

Example response (multiple entities)

{
  "data": [
    {
      "id": "1234",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "stock patched",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "USD"
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1234"
      }
    },
    {
      "id": "1235",
      "type": "derivatives_underlying_assets",
      "attributes": {
        "entity_name": "bond patched",
        "entity_type": "SECURITY",
        "underlying_type": "PRICE",
        "base_currency": "GBP"
      },
      "links": {
        "self": "/v1/derivatives_underlying_assets/1235"
      }
    }
  ]
}

Delete underlying asset by ID

DELETE /v1/derivatives/underlying_assets/:id

Deletes an underlying asset by ID.

Example request

curl -X DELETE "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/1234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/vnd.api+json"

Response codes

204 No Content -- Success
403 Forbidden -- Not permitted to make the request
404 Not Found -- An entity with the given ID is not available to the requester

Delete underlying assets

DELETE /v1/derivatives/underlying_assets

Deletes multiple underlying assets by ID, ignoring any that are not available to the requester.

Example request

curl -X DELETE "https://{firm}.addepar.com/api/v1/derivatives/underlying_assets" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": [
      {
        "type": "derivatives_underlying_assets",
        "id": "1234"
      },
      {
        "type": "derivatives_underlying_assets",
        "id": "1235"
      }
    ]
  }'

Response codes

204 No Content -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- Not permitted to make the request

📘 Related resources

Derivatives | Derivatives Migration