How do I upload corporate actions to a corporate action source?

Providing you have suitable access control permissions, you can upload corporate actions to a corporate action source.

• Method 1: Using the LUSID API
• Method 2: Using the LUSID web app
• Method 3: Using Luminesce

Using the LUSID API

You can upload an unbounded number of corporate actions in a single API call:

1. Obtain an API access token.
2. Call the UpsertInstrumentEvents API with the scope and code of a particular corporate action source, and specifying in the body of the request:
   • An instrumentEventId that uniquely identifies this corporate action in the corporate action source.
   • An instrument identifier (type and value) in the instrumentIdentifiers field that resolves to an instrument in the LUSID Security Master.
   • An instrumentEventType of TransitionEvent.
   • An announcementDate. Note this field is informational.
   • An exDate. This is the date and time at which LUSID applies the corporate action to each portfolio with a holding in the affected instrument.
   • A recordDate. Note this field is informational.
   • A paymentDate. This is the date and time at which LUSID settles the corporate action in each portfolio.
   • A single inputTransition with a unitsFactor and a costFactor.
   • At least one outputTransitions, each with:
     • An instrument identifier (type and value) in the instrumentIdentifiers field that resolves to an instrument in the LUSID Security Master. This can be the same instrument, or a different one.
     • A unitsFactor and a costFactor. The ratio of the two units factors determines the impact of the corporate action on the quantity of the holding, and the ratio of the two cost factors determines the impact of the corporate action on the cost basis of the holding.

     See how to model different kinds of corporate action.

   • Optionally, one or more properties to extend the data model. These properties must be from the InstrumentEvent domain.

Consider the following example, of a corporate action uploaded to a corporate action source with a scope of Example-CAS-scope and code of Example-CAS-code (highlighted in red in the URL). For each unit held in an instrument with FIGI BBG000BPH459, LUSID increases the holding in the USD currency instrument by 0.17 units (that is, cents). The cost basis of both holdings is unaffected:

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources/Example-CAS-scope/Example-CAS-code/instrumentevents'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '[
  {
    "instrumentEventId": "MSCashDividend-2023-02-13",
    "instrumentIdentifiers": {
      "Instrument/default/Figi": "BBG000BPH459"
    },
    "description": "Cash dividend of 17 cents per share",
    "instrumentEvent": {
      "instrumentEventType": "TransitionEvent",
      "announcementDate": "2023-02-01T00:00:00.0000000+00:00",
      "exDate": "2023-02-13T00:00:00.0000000+00:00",
      "recordDate": "2023-02-13T00:00:00.0000000+00:00",
      "paymentDate": "2023-02-17T00:00:00.0000000+00:00",
      "inputTransition": {
        "unitsFactor": 1,
        "costFactor": 0
      },
      "outputTransitions": [
        {
          "instrumentIdentifiers": {
            "Instrument/default/Currency": "USD"
          },
          "unitsFactor": 0.17,
          "costFactor": 0
        }
      ]
    },
    "properties": [
      {
        "key": "InstrumentEvent/CA/Type",
        "value": {
          "labelValue": "CashDividend"
        }
      }
    ]
  }
]'

We recommend checking the failed section of the response (highlighted in red) for corporate actions that fail to load. Successful corporate actions are listed in the values section:

{
  "failed": {},
  "values": {
    "MSCashDividend-2023-02-13": {
      "instrumentEventId": "MSCashDividend-2023-02-13",
      "corporateActionSourceId": {
        "scope": "Example-CAS-scope",
        "code": "Example-CAS-code"
      },
      "instrumentIdentifiers": {
        "Instrument/default/Figi": "BBG000BPH459"
      },
      "lusidInstrumentId": "LUID_00003DGK",
      "instrumentScope": "default",
      "description": "Cash dividend of 17 cents per share",
      "eventDateRange": {
        "start": "2023-02-13T00:00:00.0000000+00:00",
        "end": "2023-02-17T00:00:00.0000000+00:00"
      },
      "instrumentEvent": {
        "announcementDate": "2023-02-01T00:00:00.0000000+00:00",
        "exDate": "2023-02-13T00:00:00.0000000+00:00",
        "recordDate": "2023-02-13T00:00:00.0000000+00:00",
        "paymentDate": "2023-02-17T00:00:00.0000000+00:00",
        "inputTransition": {
          "unitsFactor": 1,
          "costFactor": 0
        },
        "outputTransitions": [
          {
            "instrumentIdentifiers": {
              "Instrument/default/Currency": "USD"
            },
            "unitsFactor": 0.17,
            "costFactor": 0,
            "lusidInstrumentId": "CCY_USD",
            "instrumentScope": "default"
          }
        ],
        "instrumentEventType": "TransitionEvent"
      },
      "properties": [
        {
          "key": "InstrumentEvent/CA/Type",
          "value": {
            "labelValue": "CashDividend"
          }
        }
      ]
    }
  },
  ...
}

Using the LUSID web app

Coming soon