Retrieving version information for entities

  • Updated on Apr 24, 2026
  • Published on Sep 26, 2024
Prev Next

LUSID stores version information for most types of entity. See how to audit change history.

For example, a call to the GetPortfolio API for a portfolio identified by a particular scope and code returns a version object:

{ 
  "id": {
    "scope": "Equities",
    "code": "US-Growth"
  },
  "type": "Transaction",
  "displayName": "Instructed settlement portfolio",
  "created": "2025-01-01T00:00:00.0000000+00:00",
  "version": {
    "effectiveFrom": "2026-04-21T08:02:21.9248910+00:00",
    "asAtDate": "2026-04-21T08:02:21.7861670+00:00",
    "asAtCreated": "2026-04-09T10:28:32.4468080+00:00",
    "userIdCreated": "00u91lo2d7X42sfse2p7",
    "requestIdCreated": "2026040910-b05f687e721f476fb894455780399f12",
    "reasonCreated": "",
    "asAtModified": "2026-04-20T11:35:59.0394510+00:00",
    "userIdModified": "00u91lo2d7X42sfse2p7",
    "requestIdModified": "2026042011-d26f7daf9a24444c80e8f6c6ea189d09",
    "reasonModified": "",
    "asAtVersionNumber": 6,
    "entityUniqueId": "668bbeef-55d8-4f0a-a3ff-803de058ab75"
  },
  "isDerived": false,
  "baseCurrency": "GBP",
  ...
  }
}

Important: Ignore the deprecated version.effectiveFrom and version.asAtDate fields. Instead, use:

  • version.asAtCreated for the date at which the first version of the entity begins.

  • version.asAtModified for the date at which the current version begins.

Note the following:

  • The asAtVersionNumber of a newly-created entity is 1, so the example portfolio above has been modified five times. See every change to every version.

  • You can use requestIdCreated/requestIdModified to look up more information about the underlying API request from the Insights service.

  • You can use userIdCreated/userIdModified to look up more information about the responsible user from the Identity service.

  • reasonCreated/reasonModified is only likely to be populated if the version is a staged modification awaiting approval.

  • You can filter most types of entity by version fields. More information.

  • Quotes and transactions do not have a version object; instead, information is provided by:

    • For transactions, the entryDateTime field.

    • For quotes, the uploadedBy and asAt fields.

Getting notified about changes

You can subscribe to system events to get notified when entities are created, updated or deleted. For example, the following call to the CreateSubscription API subscribes to the PortfolioUpdated system event for any portfolio in the Equities scope by any user other than one: 

curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "id": {
    "scope": "MySubscriptions",
    "code": "PortfolioUpdates"
  },
  "displayName": "PortfolioUpdatesByOtherUsers",
  "description": "Subscribes to all PortfolioUpdated events where the user performing the update is not me.",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioUpdated",
    "filter": "Header.userId neq '00uji4twb4jDcHGjN2p8' and Body.portfolioScope eq 'Equities'"
  }
}"

Learn more about the Notification Service.

© 2025 FINBOURNE Technology