Retrieving version information and tracking changes

LUSID keeps entities up-to-date with versioning information so you can always track an entity’s history and monitor changes.

For example, you could call the GetPortfolio API, passing in an API access token and the scope and code of a portfolio…

 curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios/Finbourne-Examples/Global-Portfolio"
  -H "Authorization: Bearer <your-API-access-token>"

…to retrieve version information for the portfolio. Part of a response is as follows:

 {
  "href": "https://<your-domain>.lusid.com/api/api/portfolios/Finbourne-Examples/Global-Portfolio?effectiveAt=2024-09-26T10%3A35%3A13.0145150%2B00%3A00&asAt=2024-09-26T10%3A35%3A08.3789540%2B00%3A00",
...
  "created": "2024-07-18T00:00:00.0000000+00:00",
  "version": {
    "effectiveFrom": "2024-09-26T10:35:13.0145150+00:00",
    "asAtDate": "2024-09-26T10:35:08.3789540+00:00",
    "asAtCreated": "2024-07-18T08:22:39.0312800+00:00",
    "userIdCreated": "00uji4twb4jDcHGjN2p7",
    "requestIdCreated": "0HN56QQGS6U5E:000000A0",
    "asAtModified": "2024-09-20T11:57:25.5487110+00:00",
    "userIdModified": "00uji4twb4jDcHGjN2p7",
    "requestIdModified": "8b61dae9-e29e-4793-b052-cacd86624690",
    "asAtVersionNumber": 9,
    "entityUniqueId": "3072dbce-bcf2-4d8e-b27b-96ad73258efe"
  },
 ...
}

Note the following:

• You can use the requestIdCreated and requestIdModified values to retrieve more information for the respective requests from the Insights service.

• You can filter most types of entities by version fields. Read more on filtering entities based on version information.

  Important

  Do not use 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.

• You can specify an asAt value when retrieving an entity to get the entity version at the date specified. For example, passing in an asAt of 2024-09-19 to the URL when calling the GetPortfolio API…

   curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios/Finbourne-Examples/Global-Portfolio?asAt=2024-09-19"
    -H "Authorization: Bearer <your-API-access-token>"

  …gives a response containing the previous portfolio version, with an asAtVersionNumber of 8:

   {
  ...
    "version": {
     ...
      "asAtModified": "2024-09-17T11:51:02.1582990+00:00",
      "userIdModified": "00uji4twb4jDcHGjN2p7",
      "requestIdModified": "0HN6MUO47F88L:000001AD",
      "asAtVersionNumber": 8,
      "entityUniqueId": "3072dbce-bcf2-4d8e-b27b-96ad73258efe"
    },
    ...
  }

• Quotes and transactions do not display version information as shown above; this information is instead provided by:

  • For transactions, the entryDateTime field

  • For quotes, the uploadedBy and asAt fields.

• You can pass the user ID from userIdCreated or userIdModified into the GetUser API to find out more information about the user, such as their name and assigned roles. For example:

   curl -X GET "https://<your-domain>.lusid.com/identity/api/users/00uji4twb4jDcHGjN2p7"
    -H "Authorization: Bearer <your-API-access-token>"

  Part of a response is as follows:

  {
    "id": "00uji4twb4jDcHGjN2p7",
    "alternativeUserIds": {},
    "emailAddress": "joe.bloggs@acme.com",
    "login": "joe.bloggs@acme.com",
    "firstName": "Joe",
    "lastName": "Bloggs",
    "roles": [
      {
        "id": "00gji4uidsjkIepGF2p7",
        "roleId": {
          "scope": "LUSID_SYSTEM",
          "code": "lusid-administrator"
        },
        "source": "LusidUser",
        "name": "lusid-administrator",
        "description": "LUSID Administrators. These users have access to all non-system resources in this LUSID account",
        "samlName": "lusid:LUSID_SYSTEM:lusid-administrator"
      },
      ...
    ],
    "type": "Personal",
    "status": "ACTIVE",
    "external": false,
    ...
  }

Getting notified about changes to entities

You can use filters to set up notifications so that you get notified whenever a particular entity is updated. For example, you could subscribe to the PortfolioUpdated event for portfolio updates by any other user than yourself by calling the CreateSubscription API:

curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "id": {
    "scope": "Finbourne-Examples",
    "code": "Portfolio-Updated"
  },
  "displayName": "PortfolioUpdatedByOtherUser",
  "description": "Subscribes to all PortfolioUpdated events where the user performing the update is not me.",
  "status": "Active",
  "matchingPattern": {
    "eventType": "PortfolioUpdated",
    "filter": "Header.userId neq '00ubs2temhwlYz2lI2p7'"
  }
}"

Note the filter, where you can specify LUSID filtering syntax to subscribe to events conditionally. Learn more about the Notification Service.