Upsert investment

Create an Investment if none exists with the given Tracking ID, or update the existing one otherwise.

This is an idempotent operation: calling it twice with the same payload results in the same end state. Safe to retry on network failure, or to replay as part of a scheduled sync from your portfolio accounting system or fund administrator's data.

Matching rule

The Investment is matched by the trackingId you supply in the request body. trackingId is required — requests without a trackingId are rejected with a 400 Bad Request.

Response

The response always includes the full Investment object plus a result field:

  • "result": "created" — no match was found, a new Investment was created under the supplied fundLegalEntityId.
  • "result": "updated" — an existing Investment was found and its fields were updated.

Field semantics

FieldCreateUpdate
trackingIdRequired (match key).Required (match key).
nameRequired.Replace if present; omit = unchanged.
fundLegalEntityIdRequired.Ignored — Investments are tied to their fund legal entity for life.
investmentEntityIdRequired.Ignored — Investments cannot be reassigned to a different IE via this endpoint.
statusOptional; defaults to "active".Replace if present; omit = unchanged.
fundFeeIds, shareClassIds, closeIds, tagsOptional; defaults to [].Replace if present (empty array clears); omit = unchanged.
commitmentAmount, balanceAmount, balanceUpdatedDate, createdDate, effectiveDate, noteOptional.Replace if present; omit = unchanged.

Validation errors return 400 Bad Request with the offending field name.

Bulk upsert mode (caveat)

When using mode: "upsert" on the bulk POST /investments/import endpoint, every per-row field is applied to the matched Investment — there is no way to express "leave this field unchanged" within a single bulk row. Use the individual upsert endpoint above for partial updates.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The ID of the Firm object

Body Params
string

ID of the parent fund legal entity. Required when creating a new investment; ignored on update.

string

ID of the linked investment entity. Required on create. Ignored on update — investments cannot be reassigned to a different IE via this endpoint.

string
required

Customer-supplied Tracking ID used to match an existing Investment. Required.

string

Required when creating a new Investment. On update, omit to leave the name unchanged.

fundFeeIds
array of objects

Omit to leave unchanged on update; pass an empty array to clear.

fundFeeIds
number
deprecated

Deprecated; use commitments. Will be removed on June 1, 2027. In a response, the amount in commitments in the fund legal entity's current default currency, or absent when there is none in that currency. In a request, sets only the default currency's amount and keeps the amounts in other currencies; on update, null or omitting it leaves the amounts unchanged. Send this field or commitments, not both.

number
deprecated

Deprecated; use balances. Will be removed on June 1, 2027. In a response, the amount in balances in the fund legal entity's current default currency, or absent when there is none in that currency. In a request, sets only the default currency's amount and keeps the amounts in other currencies; on update, null or omitting it leaves the amounts unchanged. Send this field or balances, not both.

commitments
array of objects

Total commitment of the investment, one amount per currency. Each item must have an amount. On create, an item without a currency uses the fund legal entity's default currency. On update, the list replaces the current one: pass an empty array to clear it, or omit it to leave it unchanged, and an item without a currency keeps the currency at the same position in the current list as responses order it, or uses the default currency when there is none. Responses list the fund legal entity's current default currency first, then the others by currency code. A supported currency the fund legal entity does not have yet is added to it.

commitments
balances
array of objects

Balance of the investment, one amount per currency. Each item must have an amount. On create, an item without a currency uses the fund legal entity's default currency. On update, the list replaces the current one: pass an empty array to clear it, or omit it to leave it unchanged, and an item without a currency keeps the currency at the same position in the current list as responses order it, or uses the default currency when there is none. Responses list the fund legal entity's current default currency first, then the others by currency code. A supported currency the fund legal entity does not have yet is added to it.

balances
date
string
enum
Defaults to active

Defaults to active on create. Omit to leave unchanged on update.

Allowed:
date
date
deprecated

Deprecated; use effectivePeriods. Will be removed on June 1, 2027. In a response, the earliest period's start, or absent when there are none — so an investment with a gap in its periods reads as continuously effective since the first one. In a request, writes through to the periods: with none it creates one open-ended period, otherwise it moves the earliest period's start; on update, null or omitting it leaves the periods unchanged. Send this field or effectivePeriods, not both.

effectivePeriods
array of objects

Periods the investment was effective, earliest first. An empty list is valid — an investment may be active with no dates recorded. Periods must not overlap (an end date is included in its period), at most one may be open-ended, and the open-ended one must be the latest. On update the list replaces the current one: pass an empty array to clear it, or omit it to leave it unchanged.

effectivePeriods
string
tags
array of strings

Omit to leave unchanged on update; pass an empty array to clear.

tags
shareClassIds
array of objects

Omit to leave unchanged on update; pass an empty array to clear.

shareClassIds
closeIds
array of objects

Omit to leave unchanged on update; pass an empty array to clear.

closeIds
Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json