Working with portfolios

SnapshotsCopy Anchor Link

A portfolio is a set of holdings at a date. Each date is a snapshot. The snapshot_at you send is moved to the end of its quarter, so 2026-05-14 is stored as 2026-06-30. A portfolio holds at most one snapshot per quarter.

Stored portfolios appear in your organization in the Connect Earth app. The API does not read them back yet: the other routes take the holdings in the request body.

Create a portfolioCopy Anchor Link

Send the holdings with POST /portfolios. name, snapshot_at and holdings are required. currency is an ISO 4217 code and defaults to USD; a code that is not recognized creates the portfolio in EUR.

Give every holding a name, a currency and a non-zero market_value. weight and market_value must be numbers. Use null as the ISIN for cash or instruments without an ISIN.

curl https://eco.datia.app/portfolios \
  --request POST \
  --header "Content-Type: application/json" \
  --header "x-api-key: $CE_API_KEY" \
  --data @portfolio.json

{
  "name": "Pension fund A",
  "identifier": "pension-fund-a",
  "currency": "USD",
  "snapshot_at": "2026-06-30",
  "holdings": [
    { "name": "Apple Inc.", "isin": "US0378331005", "instrument_type": "stock", "currency": "USD", "weight": 30, "market_value": 3000000 },
    { "name": "Microsoft Corp.", "isin": "US5949181045", "instrument_type": "stock", "currency": "USD", "weight": 25, "market_value": 2500000 },
    { "name": "iShares Core MSCI World UCITS ETF", "isin": "IE00B4L5Y983", "instrument_type": "etf", "currency": "USD", "weight": 25, "market_value": 2500000 },
    { "name": "Bund 2.6% 2033", "isin": "DE000BU2Z015", "instrument_type": "sovereign-bond", "currency": "EUR", "weight": 15, "market_value": 1500000 },
    { "name": "Cash", "isin": null, "instrument_type": "cash", "currency": "USD", "weight": 5, "market_value": 500000 }
  ]
}

The response (201) gives the portfolio's identifier:

{
  "identifier": "datia-portfolio:12345_pension-fund-a",
  "metadata": {
    "message": "Fund created successfully at 2026-06-30"
  }
}

The returned identifier has the form datia-portfolio:<organization id>_<your identifier>. Store it: it is the value you pass to PUT and DELETE /portfolios/{identifier}, and it must match exactly.

Always send an identifier. Portfolios created without one share the same identifier, so you cannot update or delete them one by one. Use only letters, digits, - and _ in it, so the returned value can be used in a URL path as is.

Replace a snapshotCopy Anchor Link

Send POST /portfolios again with the same identifier and a date in the same quarter. The holdings for that quarter are replaced. A date in a different quarter adds a new snapshot to the same portfolio. Both return 201. Whenever the portfolio already exists, the message reads "Fund updated successfully at" followed by the quarter-end date, whether a snapshot was replaced or added.

Only the holdings change. To change name or currency of an existing portfolio, use PUT /portfolios/{identifier}.

List portfoliosCopy Anchor Link

GET /portfolios lists every portfolio in your organization, including portfolios created in the Connect Earth app, each with its identifier and the quarter-end dates that have holdings, oldest first. Snapshots older than about five years are not listed.

{
  "data": {
    "members": 4,
    "funds": [
      {
        "identifier": "datia-portfolio:12345_pension-fund-a",
        "name": "Pension fund A",
        "snapshots": ["2026-03-31", "2026-06-30"]
      }
    ]
  },
  "metadata": {
    "message": "Organization metadata successfully retrieved"
  }
}

Rename or change currencyCopy Anchor Link

PUT /portfolios/{identifier} updates the name or currency of a portfolio. Send only the fields you want to change. An unknown currency code is ignored.

curl https://eco.datia.app/portfolios/datia-portfolio:12345_pension-fund-a \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "x-api-key: $CE_API_KEY" \
  --data '{"name":"Pension fund A (EUR)","currency":"EUR"}'

{
  "identifier": "datia-portfolio:12345_pension-fund-a",
  "metadata": {
    "message": "Fund metadata updated successfully with id: 67890"
  }
}

Delete a snapshotCopy Anchor Link

DELETE /portfolios/{identifier} deletes one snapshot. Send its date as snapshot_at in the JSON body. Like on create, the date is moved to the end of its quarter.

PUT and DELETE work on any portfolio in your organization, including portfolios created in the Connect Earth app.

curl https://eco.datia.app/portfolios/datia-portfolio:12345_pension-fund-a \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "x-api-key: $CE_API_KEY" \
  --data '{"snapshot_at":"2026-06-30"}'

{
  "identifier": "datia-portfolio:12345_pension-fund-a",
  "metadata": {
    "message": "Fund snapshot deleted successfully"
  }
}

metadata.message says what happened: