Cash, Assets & AssetMixes

The value of an investorAccount is comprised of two components:

• Cash: all funds that are in the account
• Assets: all “investments” that are in the account

Both cash and assets are tracked in ledgers.

Cash

We consider cash to be any fund that’s in the account and not (fully) invested. GiroPro recognizes different types of cash, these types include:

• Main: cash in GiroPro with no particular designation
• Reserved: cash that has been invested but the investment hasn’t been fully executed
• InTransfer: cash that has been withdrawn from the investorAccount to the investor’s bank account but hasn’t been fully transferred
• ManagementFee: fee paid to GiroProvider

There are multiple ways to retrieve cash from an investorAccount. But we recommend using one of the following.

GET /PortfolioGetByInvestorAccountId/

The specifics of this endpoint can be found here.

GET /CashGetByInvestorAccountId/

The /CashGetByInvestorAccountId/ endpoint returns a CashAggregatedItem for the provided investorAccountId.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/CashGetByInvestorAccountId/<labelId>/<investorAccountId>';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This endpoint returns a PengineResult containing a CashAggregatedItem:

{
    "success": true,
    "httpStatusCode": 200,
    "errors": [],
    "totalCount": 0,
    "items": [
        {
            "return_type": "CashAggregatedItem",
          	"id": "789ba1a1a21a-321a-ba21-a21a-1a21a789",
            "investorAccountId": "4563a12a1-a12a-12ab-a123-a12a1a1ab456",
            "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
            "ledgerId": "654ba1a1a21a-321a-ba21-a21a-1a21a3654",
          	"currency": "EUR",
            "creationDate": "2008-02-01T00:00:00Z",
            "validFromDate": "2008-02-01T00:00:00Z",
            "valueTimestamp": 638754812367423830,
            "main": 0.0,
            "inTransfer": 0.0,
            "reserved": 0.0,
            "managementFee": 0.0,
            "nav": 0.0,
            "total": 0.0,
            "bankAccountIds": [
                // list of bank account IDs
            ],
            "bankAccounts": [
                {
                    "iban": "NL00ABCD0123456789",
                    "bic": "ABCDNL1A",
                    "name": "KlaasSpanjaard",
                    "id": "321ba1a1a21a-321a-ba21-a21a-1a21a321",
                    "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
                    "ownerType": "InvestorAccount",
                    "ownerId": "4563a12a1-a12a-12ab-a123-a12a1a1ab456", // id of the investor account
                    "noAllocationTransactionCodes": []
                }
            ],
            "cashLedgerItems": [
                {
                    "id": "4a614b6b-b33a-47a3-bd32-8c036f12b6f0",
                    "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
                    "ledgerType": "Reserved",
                    "ledgerId": "2794f873-a7c7-4b48-9f4c-61d718b7d863"
                },
                {
                    "id": "228aa2b6-b08f-4f43-982b-9084a116ccb2",
                    "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
                    "ledgerType": "Main",
                    "ledgerId": "100a11a4-5727-4e58-8329-b200661bbc15"
                },
                {
                    "id": "d917745c-db4f-42ed-9530-52238d210662",
                    "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
                    "ledgerType": "InTransfer",
                    "ledgerId": "5eb68ad8-9d6d-4072-b77b-f1b00d288ed5"
                }
            ]
        }
    ]
}

When to use

Since the result of the /CashGetByInvestorAccountId/ endpoint is already included in the result of the /PortfolioGetByInvestorAccountId/ endpoint it is generally not necessary to use the prior endpoint if the portfolio has already been retrieved.

---

Assets

We consider assets to be any actualized investment in the account.

GET /PortfolioGetByInvestorAccountId/

The specifics of this endpoint can be found here. The response of this endpoint contains a list of AssetItems, which slightly differ from AssetAggregatedItems. Here’s an example of what an AssetItem looks like:

{
  "assetId": "1c092ed5-1bfb-44fa-9748-1af365962298",
  "units": 3139.9821,
  "unitsReserved": 0.0,
  "openingPriceDate": "2024-05-17T00:00:00Z",
  "portfolioId": "a5fecff1-1312-41c5-bf58-6b6be55fbb41",
  "openingPrice": 55.989600,
  "averagePurchasePrice": 49.9482,
  "totalValue": 175806.34,
  "invested": 156836.34,
  "unrealizedResult": 18970.00,
  "navValue": 0.0,
  "unitsDividend": 0.0,
  "cashDividend": 0.0,
  "distributionPercentage": 1.0,
  "cashLedgerId": "d0f99ff7-1828-45ae-bc5c-f8f2b4b160de",
  "assetLedgerId": "f91a67e2-f7bc-4fd6-982a-e5751e88a960",
  "assetReservedLedgerId": "a537c2e1-3bb1-41db-9b83-9db3cbb11d7e",
  "assetDividendLedgerId": "592978b8-f00a-4f18-906b-a23e8c203ba8",
  "dividendLedgerId": "e20017fc-3064-4ff4-be65-39cd9c42477e",
  "resultLedgerId": "0b5778f3-2164-4435-8887-20286c5d01d8",
  "navLedgerIds": [],
  "asset": {
    "objectType": "AssetItem",
    "assetType": "Stock",
    "cashLedgerId": "751411fe-27fd-4772-88c3-d18b3b22e325",
    "assetLedgerId": "0568a694-4c28-4542-b79b-e2039a795cfe",
    "cashReservedLedgerId": "6e7cc471-9dc8-4db4-afa7-e9258d1ede05",
    "assetReservedLedgerId": "df0dae1a-e145-4eb3-a2f5-c833e50840e2",
    "assetDividendLedgerId": "91bc4ff3-d887-4e48-bd3d-6d78e88187fb",
    "cashDividendLedgerId": "f4f8d78f-a424-4348-af3c-e7c1826b5877",
    "cashDividendTaxLedgerId": "068f6420-c20a-41eb-8384-120de5a71a07",
    "resultLedgerId": "bee01bc0-ffc3-48eb-86f8-8189cd75270c",
    "isin": "NL0015000PV3",
    "interestRate": 0.0,
    "marketId": "a372370d-33d0-462f-81e4-ee82b9f4c84b",
    "bbgId": "",
    "assetPrices": [],
    "ongoingChargesFigures": [],
    "stockDividend": false,
    "country": "NLD",
    "priceType": "Normal",
    "assetDiscriminator": "Asset",
    "id": "1c092ed5-1bfb-44fa-9748-1af365962298",
    "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
    "temporarilyBlocked": false,
    "name": "Aandelen Wereldwijd Totaal Klasse B",
    "description": "",
    "externalName": "06AWSB",
    "currency": "EUR",
    "rebalance": true,
    "miFid": true,
    "buy": true,
    "sell": true,
    "accrual": false,
    "decrement": false,
    "reInvestable": false,
    "endOfMonthPrice": false,
    "allowedInAssetMix": true,
    "bankingStatementCode": "^(?!.*(((aand).*(ob))|((ob).*(aand))))(.*((aand)\\S*\\s*((wer)|(wrld)|(ww)))|(((wer)|(wrld)|(ww))\\S*\\s*((tot)|(ttl)))|((aand)\\S*\\s*((tot)|(ttl)))|.*(11AWRL))",
    "autoRebalance": false,
    "versionState": "None",
    "isNew": false
  }
}

POST /Assets

The /Assets endpoint retrieves the assets of an investorAccount for the provided investorAccountId and labelId.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/AssetAggregator/Assets?investorAccountId=<investorAccountId>';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify({ labelId: <labelId> })    
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This endpoint returns a PengineResult containing a list of AssetAggregatedItems:

{
    "success": true,
    "httpStatusCode": 200,
    "errors": [],
    "totalCount": 11,
    "items": [
        {
            "return_type": "AssetAggregatedItem",
          	"assetType": "Stock",
            "cashLedgerId": "751411fe-27fd-4772-88c3-d18b3b22e325",
            "assetLedgerId": "0568a694-4c28-4542-b79b-e2039a795cfe",
            "cashReservedLedgerId": "6e7cc471-9dc8-4db4-afa7-e9258d1ede05",
            "assetReservedLedgerId": "df0dae1a-e145-4eb3-a2f5-c833e50840e2",
            "assetDividendLedgerId": "91bc4ff3-d887-4e48-bd3d-6d78e88187fb",
            "cashDividendLedgerId": "f4f8d78f-a424-4348-af3c-e7c1826b5877",
            "cashDividendTaxLedgerId": "068f6420-c20a-41eb-8384-120de5a71a07",
            "resultLedgerId": "bee01bc0-ffc3-48eb-86f8-8189cd75270c",
            "isin": "NL0012000AB1",
            "interestRate": 0.0,
            "marketId": "a372370d-33d0-462f-81e4-ee82b9f4c84b",
            "bbgId": "",
          	"stockDividend": false,
            "country": "NLD",
            "priceType": "Normal",
            "assetDiscriminator": "Asset",
            "id": "1c092ed5-1bfb-44fa-9748-1af365962298",
            "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
            "temporarilyBlocked": false,
            "name": "Shares World Wide",
            "description": "",
            "externalName": "06AWSB",
            "currency": "EUR",
            "rebalance": true,
            "miFid": true,
            "buy": true,
            "sell": true,
            "accrual": false,
            "decrement": false,
            "reInvestable": false,
            "endOfMonthPrice": false,
            "allowedInAssetMix": true,
            "bankingStatementCode": "^(?!.*(((aand).*(ob))|((ob).*(aand))))(.*((aand)\\S*\\s*((wer)|(wrld)|(ww)))|(((wer)|(wrld)|(ww))\\S*\\s*((tot)|(ttl)))|((aand)\\S*\\s*((tot)|(ttl)))|.*(11AWRL))",
            "autoRebalance": false,
            "versionState": "None",
            "isNew": false,
          	"currentPrice": {
                "id": "156e3a88-893f-4d33-a197-1d0e9ca00a12",
                "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                "assetId": "1c092ed5-1bfb-44fa-9748-1af365962298",
                "dateTimeOfPrice": "2024-05-17T00:00:00Z",
                "price": 55.9896,
                "momentType": "Opening",
                "marketDayId": "1916fef4-2225-4946-8c91-a25438f833b3",
                "corrected": false,
                "priceType": "Normal"
            },
            "assetPrices": [],
            "ongoingChargesFigures": [
                {
                    "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                    "assetId": "1c092ed5-1bfb-44fa-9748-1af365962298",
                    "percentage": 0.0025,
                    "startDate": "2022-01-01"
                }
            ],
            "marketAggregatedItem": {
                "return_type": "MarketAggregatedItem",
                "id": "a372370d-33d0-462f-81e4-ee82b9f4c84b",
                "name": "CoNAAMBRS",
                "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                "assetIds": [
                    "1c092ed5-1bfb-44fa-9748-1af365962298",
                    "f7ed7f49-bd52-4edf-aa6d-64c8fbfdfc3a",
                    "be5f5770-2301-4296-9230-69c88ac6a637",
                    "45320bbc-5f92-4ac3-a04c-6dcdf53f533e",
                    "035598ee-59f4-4c27-98c3-80b1e8b790b0",
                    "d0336cb9-119d-46c1-b01b-832833d75426",
                    "5da7c92d-0930-42fb-adf3-c1a5b0f3d0ce",
                    "52b66b65-aed6-4cea-9957-c645e60ba34a",
                    "7ef0fc95-8882-4ba9-ab12-c8a07fde8bed",
                    "8823cbb4-1ccc-4682-b8ea-cd4c67857cbf"
                ],
                "defaultCutoffTime": "23:59:00",
                "defaultProcessingDays": 0,
                "timeZoneId": "Europe/Amsterdam",
                "days": [
                	// list of MarketDayItems
                ]
            }
        },
        // more AssetAggregatedItems
    ]
}

GET /AssetGetById/

The /AssetGetById/ endpoint returns a single AssetAggregatedItem for the provided labelId and assetId.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/AssetAggregator/AssetGetById/<labelId>/<assetId>';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

{
    "success": true,
    "httpStatusCode": 200,
    "errors": [],
    "totalCount": 0,
    "items": [
        {
            "return_type": "AssetAggregatedItem",
          	"assetType": "Stock",
            "cashLedgerId": "751411fe-27fd-4772-88c3-d18b3b22e325",
            "assetLedgerId": "0568a694-4c28-4542-b79b-e2039a795cfe",
            "cashReservedLedgerId": "6e7cc471-9dc8-4db4-afa7-e9258d1ede05",
            "assetReservedLedgerId": "df0dae1a-e145-4eb3-a2f5-c833e50840e2",
            "assetDividendLedgerId": "91bc4ff3-d887-4e48-bd3d-6d78e88187fb",
            "cashDividendLedgerId": "f4f8d78f-a424-4348-af3c-e7c1826b5877",
            "cashDividendTaxLedgerId": "068f6420-c20a-41eb-8384-120de5a71a07",
            "resultLedgerId": "bee01bc0-ffc3-48eb-86f8-8189cd75270c",
            "isin": "NL0012000AB1",
            "interestRate": 0.0,
            "marketId": "a372370d-33d0-462f-81e4-ee82b9f4c84b",
            "bbgId": "",
          	"stockDividend": false,
            "country": "NLD",
            "priceType": "Normal",
            "assetDiscriminator": "Asset",
            "id": "1c092ed5-1bfb-44fa-9748-1af365962298",
            "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
            "temporarilyBlocked": false,
            "name": "Shares World Wide",
            "description": "",
            "externalName": "06AWSB",
            "currency": "EUR",
            "rebalance": true,
            "miFid": true,
            "buy": true,
            "sell": true,
            "accrual": false,
            "decrement": false,
            "reInvestable": false,
            "endOfMonthPrice": false,
            "allowedInAssetMix": true,
            "bankingStatementCode": "^(?!.*(((aand).*(ob))|((ob).*(aand))))(.*((aand)\\S*\\s*((wer)|(wrld)|(ww)))|(((wer)|(wrld)|(ww))\\S*\\s*((tot)|(ttl)))|((aand)\\S*\\s*((tot)|(ttl)))|.*(11AWRL))",
            "autoRebalance": false,
            "versionState": "None",
            "isNew": false,
          	"currentPrice": {
                "id": "156e3a88-893f-4d33-a197-1d0e9ca00a12",
                "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                "assetId": "1c092ed5-1bfb-44fa-9748-1af365962298",
                "dateTimeOfPrice": "2024-05-17T00:00:00Z",
                "price": 55.9896,
                "momentType": "Opening",
                "marketDayId": "1916fef4-2225-4946-8c91-a25438f833b3",
                "corrected": false,
                "priceType": "Normal"
            },
            "assetPrices": [],
            "ongoingChargesFigures": [
                {
                    "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                    "assetId": "1c092ed5-1bfb-44fa-9748-1af365962298",
                    "percentage": 0.0025,
                    "startDate": "2022-01-01"
                }
            ],
            "marketAggregatedItem": {
                "return_type": "MarketAggregatedItem",
                "id": "a372370d-33d0-462f-81e4-ee82b9f4c84b",
                "name": "CoNAAMBRS",
                "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
                "assetIds": [
                    "1c092ed5-1bfb-44fa-9748-1af365962298",
                    "f7ed7f49-bd52-4edf-aa6d-64c8fbfdfc3a",
                    "be5f5770-2301-4296-9230-69c88ac6a637",
                    "45320bbc-5f92-4ac3-a04c-6dcdf53f533e",
                    "035598ee-59f4-4c27-98c3-80b1e8b790b0",
                    "d0336cb9-119d-46c1-b01b-832833d75426",
                    "5da7c92d-0930-42fb-adf3-c1a5b0f3d0ce",
                    "52b66b65-aed6-4cea-9957-c645e60ba34a",
                    "7ef0fc95-8882-4ba9-ab12-c8a07fde8bed",
                    "8823cbb4-1ccc-4682-b8ea-cd4c67857cbf"
                ],
                "defaultCutoffTime": "23:59:00",
                "defaultProcessingDays": 0,
                "timeZoneId": "Europe/Amsterdam",
                "days": [
                	// list of MarketDayItems
                ]
            }
        },
        // more AssetAggregatedItems
    ]
}

When to use

The main differences between using the /PortfolioGetByInvestorAccountId/ endpoint and the /Assets or /AssetGetById/ endpoints is the type of Asset-object they return as well as the quantity of assets returned.

Quantity

• /PortfolioGetByInvestorAccountId/: returns all assets this specific investorAccount can invest in.
• /Assets: returns all existing assets for the label, excluding assetMixes
• /AssetGetById/: return one specific asset

Types

---

AssetsMixes

An AssetMix is a collection of multiple Assets following a value-based percentual distribution. This allows investors to invest in all of the Assets in the AssetMix in accordance to the specified ratio, or to rebalance their entire portfolio to match the ratio of the AssetMix.

The ratio represents the distribution of value of the Assets in the AssetMix, not the amount of units. When investing €100 in an AssetMix with a 50-50 ratio, the underlying Assets could be distributed like this:

Name	Percentage	Price	Units	Total value
Asset A	0.5	€50	1	€50
Asset B	0.5	€2	25	€50

The AssetMix does not represent the actual ratio of Assets within the portfolio as Assets increase and decrease in value at different rates. Therefore the asset-ratio of the portfolio will certainly change over time if it is not regularly rebalanced. To see the asset-ratio of the portfolio it’s best to look at the PerformancePortfolioItems, which are part of the portfolio returned by the /PortfolioGetByInvestorAccountId/ endpoint which is documented here.

Within GiroPro AssetMixes themselves are considered assets but are treated slightly differently. Investing in an AssetMix will not result in the investor owning an amount of AssetMix assets, but rather the assets the AssetMix is comprised of in accordance to the specified ratio of the AssetMix.

GET /AssetGetById/

Since an AssetMix is an Asset we can use the ID of the AssetMix with the /AssetGetById/ endpoint, which is documented here.

The response differs slightly, because it returns an AssetMixAggregatedItem instead:

{
    "success": true,
    "httpStatusCode": 200,
    "errors": [],
    "totalCount": 0,
    "items": [
        {
            "return_type": "AssetMixAggregatedItem",
            "productIdsForAssetMix": [],
            "assetMixRecords": [
                {
                    "percentage": 0.6667,
                    "childAssetId": "be5f5770-2301-4296-9230-69c88ac6a637",
                    "childAssetName": "Aandelen Wereldwijd Totaal",
                    "parentAssetId": "997ae99d-8c1e-42d9-9bc4-d368781c2238"
                },
                {
                    "percentage": 0.3333,
                    "childAssetId": "7ef0fc95-8882-4ba9-ab12-c8a07fde8bed",
                    "childAssetName": "Obligaties Wereldwijd",
                    "parentAssetId": "997ae99d-8c1e-42d9-9bc4-d368781c2238"
                }
            ],
            "investorAccountId": "488ff6a0-c7b1-4690-b886-23076b7f01e2",
            "rebalanceOnChange": false,
            "rebalanceExecutionType": "AllAtOnce",
            "assetDiscriminator": "AssetMix",
            "id": "997ae99d-8c1e-42d9-9bc4-d368781c2238",
            "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
            "temporarilyBlocked": false,
            "name": "AssetMixName",
            "description": "",
            "externalName": "",
            "currency": "EUR",
            "rebalance": true,
            "miFid": true,
            "buy": true,
            "sell": true,
            "accrual": false,
            "decrement": false,
            "reInvestable": true,
            "endOfMonthPrice": false,
            "allowedInAssetMix": false,
            "bankingStatementCode": "",
            "autoRebalance": false,
            "versionState": "None",
            "isNew": false
        }
    ]
}

The main difference between an AssetAggregatedItem and an AssetMixAggregatedItem is that the latter contains a list of AssetMixRecordItems. An AssetMixRecordItem contains the name and ID of an asset, the ID of the assetMix and the percentage it represents within the assetMix.

POST /AssetAdd

Because an assetMix is an asset, we use the /AssetAdd endpoint to create a new assetMix, or to update an existing one.

The body of the request has to be an AssetMixAggregatedItem which, at the bare minimum, contains the properties from the example below:

{
    "return_type": "AssetMixAggregatedItem",
    "name": "assetMixName",
    "investorAccountId": "6b6cb028-6362-409d-92d6-1224fdb0084d",
    "labelId": "cd3a71f1-b9ac-4e44-a06b-f89f35beafa7",
    "productIdsForAssetMix": [
        "1dba3e6d-8305-4844-be25-640b5449093c"
    ],
    "assetMixRecords": [
        {
            "percentage": 0.5,
            "childAssetId": "d0336cb9-119d-46c1-b01b-832833d75426"
        },
        {
            "percentage": 0.5,
            "childAssetId": "5da7c92d-0930-42fb-adf3-c1a5b0f3d0ce"
        }
    ]
}

The percentages in the assetMixRecordItems have to add up to 1.0 exactly. More properties of the AssetMixAggregatedItem as seen in the example here can be added to the request body to further specify the assetMix and its functions.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/AssetAggregator/AssetAdd';  
const options = {  
  method: 'POST',  
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify(<AssetMixAggregatedItem>)   
};

fetch(url, options)  
  .then(res => res.json())  
  .then(json => console.log(json))  
  .catch(err => console.error(err));