Easily load client data into the Kurtosys App using Kurtosys APIs.
Once loaded, data can be used in client documents, portals, or websites.
What are allocations and why do I need them?
Allocations are commonly used to display data visualisations related to holdings data. They enable us to have tables of data with any number of columns. Any number of allocation tables can be created.
Functions:
- Used to load holdings data
- Used to create and display holdings data in tables, charts or graphs
For financial products like funds, allocations are used to load items like top 10 holdings, country allocations, region allocations, sector allocations etc.
When and where do I use them?
Allocations data is associated with the various Entity types: Fund, Class, Account or Benchmark. They are created in the Data Dictionary. Data is loaded once they exist in the Data Dictionary.
For example, a single class or product could have a table for sector allocations, country allocations, top 10 holdings. Essentially any table relating to holdings data.
What do I need to use them?
- Identify your data-driven elements: you must identify the page elements, across the entire solution, that must be data-driven. To allow an element to be data-driven, it has to exist in the Data Dictionary and the data must be loaded.
- Have the data: you must ensure that you have data, in the right format, to be loaded as allocations data.
- Create allocations one-by-one: creating properties in the Data Dictionary require each allocations table to be created using an individual API request.
- Load the entire table of data at once: loading allocations, unlike the creation, must be done for one product or entity at one time. If you have five different allocations tables, you must load all rows and columns for one table in one go.
Step 1: Create Allocations Table
Allocations must be created in the Data Dictionary before any data can be loaded.
Allocations need to be created for each entity level used.
For example, if holdings data will be loaded at class and fund level. Allocations tables specific to each product should be created on each level respectively.
Required fields
Field | Criteria | Description | Requirements | Example |
|---|---|---|---|---|
code | Required | A unique identifier for the property. | Lowercase without spaces. Maximum of 32 characters. Words separated by an underscore. No special characters except an underscore (_). | top_10_holdings |
entityType | Required | Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account | Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’ | FUND |
label | Required | A label for the allocation. | Descriptive name using title case. Avoid special characters. | Top 10 Holdings |
description | Required | A description of the data the property will carry. | Less than 100 characters. Use sentence case. Avoid special characters. | Top 10 holdings of the fund |
formatCode | Optional | Enables the use of an existing format code in the system. A format code will apply a number, date or currency formatting to the data value loaded. | Format codes must be added via the API before they can be applied to a property. | dd.MM.yyyy |
group | Required | A label that can be used to group similar properties together. | Must be a string value. Must be consistent across different properties of the same group. | core |
subGroup | Optional | A label of group items within a group ie a subgroup. | Must be a string value. Must be consistent across different properties of the same sub group. | documents |
extended | Optional | Indicates whether additional columns (as known as Extended Properties) will be required | If included in the API request body: must be one of two options. ‘true’ or ‘false’ | true |
includeIn | Optional | Enables the translations of data loaded against the property by automatically pulling in data values to the Translations module. | If included in the API request body: must be one of two options. ‘true’ or ‘false’ | true |
includeIn.translations | Optional | Indicates whether data loaded should be translatable | If included in the API request body: must be one of two options. ‘true’ or ‘false’ | true |
An example of allocation creation
In the following example, we’re adding a new allocation to store the top 10 holdings of the fund. The allocation table will contain 5 columns. By default, the system will provide the first two columns. One label (STRG) and one value (DCML) column. Column 1 and 5 in the below table. Three additional columns will be required and should be added to the ‘extended’ section.
| Label | effective_date | allocation_date | benchmark_value | Value |
| ASML | 202/06/12 | 2020/05/31 | 1.78 | 5.69 |
For more details on the API endpoint to be used and the minimum required parameters, see the API Documentation page.
{
"code": "top_ten_holdings",
"entityType": "CLSS",
"label": "Top 10 Holdings",
"description": "Top 10 holdings of the fund",
"group": "core",
"extended": [
{
"label": "effective_date",
"dataType": "DATE"
},
{
"label": "allocation_date",
"dataType": "DATE"
},
{
"label": "benchmark_value",
"dataType": "DCML"
}
]
}The endpoint to be used can be one of the following depending on the method:
HTTPS
- For US clients: https://api-us.kurtosys.app/config/addAllocProperty
- For UK clients: https://api-uk.kurtosys.app/config/addAllocProperty
- For EU clients: https://api-eu.kurtosys.app/config/addAllocProperty
Websocket (for bulk uploads)
- For US clients: wss://api-us.kurtosys.app/config/addAllocProperty
- For UK clients: wss://api-uk.kurtosys.app/config/addAllocProperty
- For EU clients: wss://api-eu.kurtosys.app/config/addAllocProperty
The API will respond with the below code to indicate successful creation, along with a 200 OK response code.
{
"allocationPropertyId": 12,
"code": "top_ten_holdings",
"entityType": "CLSS",
"label": "Top 10 Holdings",
"description": "Top 10 holdings of the fund",
"group": "core",
"extended": [{
"label": "effective_date",
"dataType": "DATE"
},
{
"label": "allocation_date",
"dataType": "DATE"
},
{
"label": "benchmark_value",
"dataType": "DCML"
}
]
}Create the allocation using the API
Log in to Kurtosys App to check it has been created successfully
Things to keep in mind
Correcting an error:
If an error was made during the initial creation, it can be corrected by resending the body with the necessary corrections. This should only be done if the allocation does not already have data associated with it. If data has been loaded, it should be deleted first.
Creation on different levels:
If data needs to be loaded on both class and fund levels, the allocation should be created separately on each level as it cannot be globally used across different levels.
Deleting allocations:
If an allocation should no longer carry any data, you can delete the data. Use the link below to find out how.
Step 2: Update Allocations Data
2.1 Load data
The following items should be completed before loading data:
- Create the required allocation in the Data Dictionary
- Ensure the data meets the data type requirements. For example, if a column has been created as an integer (ITRG) the data values must be rounded numbers. Decimals will be lost when loading.
Rules when loading data:
- When loading data to an allocation, all the data values for all columns and row must be loaded at once, one product or entity at a time.
- Each product or entity must have an identifier or client code that allows targeting of the product to make visualisations data-driven. This could be anything but will always be referred to as a client code in the request body.
An example of loading allocation data
In the following example, we will load data for all five columns of allocation data:
{
"entityType": "CLSS",
"clientCode": "GB00B4NVSH01",
"code": "top_ten_holdings",
"ccy": "NA",
"values": [
{
"allocation_date": "2020-05-31",
"benchmark_value": 14.2586478,
"effective_date": "2020-06-12",
"label": "Germany",
"value": 26.58166574
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 3.99073589,
"effective_date": "2020-06-12",
"label": "Spain",
"value": 13.9837997
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 23.46399746,
"effective_date": "2020-06-12",
"label": "United Kingdom",
"value": 12.67382401
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 7.03719751,
"effective_date": "2020-06-12",
"label": "Netherlands",
"value": 11.27595265
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 17.20605733,
"effective_date": "2020-06-12",
"label": "France",
"value": 9.3252636
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 16.67819671,
"effective_date": "2020-06-12",
"label": "Switzerland",
"value": 7.93485627
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 3.7192254,
"effective_date": "2020-06-12",
"label": "Denmark",
"value": 6.6532517
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 4.65283028,
"effective_date": "2020-06-12",
"label": "Sweden",
"value": 3.89795875
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 0.9073343,
"effective_date": "2020-06-12",
"label": "Norway",
"value": 3.51761507
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 1.71570487,
"effective_date": "2020-06-12",
"label": "Finland",
"value": 2.88894188
}
]
}The required request parameters remain the same as for the creation of the property.
The endpoint to be used can be one of the following depending on the method:
HTTPS
- For US clients: https://api-us.kurtosys.app>/dataloader/upsertentity
- For UK clients: https://api-uk.kurtosys.app>/dataloader/upsertentity
- For EU clients: https://api-eu.kurtosys.app>/dataloader/upsertentity
Websocket (for bulk uploads)
- For US clients: wss://api-us.kurtosys.app>/dataloader/upsertentity
- For UK clients: wss://api-uk.kurtosys.app>/dataloader/upsertentity
- For EU clients: wss://api-eu.kurtosys.app>/dataloader/upsertentity
The API will respond with the below code to indicate successful creation, along with a 200 OK response code.
Load the allocation data using the API
Log in to Kurtosys App to check it has been loaded successfully
Things to keep in mind
Correcting a specific allocation’s data value:
If an error occurred during the initial loading, you can fix it by sending the entire request body again, including all the columns and rows. Only update the data values for the specific column or row that needs correction. Do not send a request body with only the specific column or row, as this will overwrite the previously loaded data.
Deleting a specific allocation’s data value:
If an allocation should no longer carry any data, you can delete the allocation.
Creation on different levels:
If data has to be loaded at both class and fund levels, the allocation data should be loaded separately at each level. This can be done by changing the ‘type’ field to the correct level. For example, ‘CLSS’ for class level, or ‘FUND’ for fund level.
Changing the client code for each product entity:
If multiple products or entities require allocation data to be loaded, make sure to change the client code field for each API request; otherwise, you will simply overwrite the same product/entity. By extension, each product or entity code must be unique.
Ensuring data loaded matches the data format:
When loading data, it is crucial to ensure that the data matches the data format of the allocation column.
The following rules apply to each data format:
- String (STRG): The field can receive any data value but is most commonly used for text, or combinations of numbers and text.
- Decimal (DCML): The field can receive numeric values with any number of decimals. A full stop (.) must be used to indicate decimals (eg 20.50)
- Integer (ITGR): The field can also carry numeric values but cannot carry decimal numbers. (eg 40)
- Boolean (BOOL): This field is used to store true or false data values. Data values must be provided as ‘0’ or ‘1’. Zero indicates false and one indicates true.
- Date (DATE): The field can only receive and carry dates. Dates need to be formatted using the following convention: YYYY-MM-DD
- Date and Time (DTIM): The field is used to store combinations of dates and times. The following convention should be used: “YYYY-DD-MM HH:MM:SS”
2.2 Update data
The following items should be completed before updating data:
- Products and entities must already be created in the system. Each with a unique client code.
- Ensure you have identified the product/entity or list of entities that need to be updated.
- Ensure the data meets the data type requirements. For example, if a column has been created as an integer (ITRG) the data values must be rounded numbers. Decimals will be lost when loading.
Rules when updating data:
- When updating allocations all data values for all columns and rows must be loaded at once, one product or entity at a time.
- Each product or entity must have an identifier that allows targeting of the product to make visualisations data-driven. This could be anything but will always be referred to as a client code in the request body.
An example of updating allocation data
In the following example, we will update data for all five columns of allocation data. The columns remain the same, but the data has changed.
{
"entityType": "CLSS",
"clientCode": "GB00B4NVSH01",
"code": "top_ten_holdings",
"ccy": "NA",
"values": [
{
"allocation_date": "2020-05-31",
"benchmark_value": 14.2586478,
"effective_date": "2020-06-12",
"label": "Germany",
"value": 30.43166574
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 3.99073589,
"effective_date": "2020-06-12",
"label": "Spain",
"value": 23.5637997
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 23.46399746,
"effective_date": "2020-06-12",
"label": "United Kingdom",
"value": 19.67382401
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 7.03719751,
"effective_date": "2020-06-12",
"label": "Netherlands",
"value": 11.27595265
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 17.20605733,
"effective_date": "2020-06-12",
"label": "France",
"value": 9.3252636
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 16.67819671,
"effective_date": "2020-06-12",
"label": "Switzerland",
"value": 7.93485627
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 3.7192254,
"effective_date": "2020-06-12",
"label": "Denmark",
"value": 6.6532517
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 4.65283028,
"effective_date": "2020-06-12",
"label": "Sweden",
"value": 3.89795875
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 0.9073343,
"effective_date": "2020-06-12",
"label": "Norway",
"value": 3.51761507
},
{
"allocation_date": "2020-05-31",
"benchmark_value": 1.71570487,
"effective_date": "2020-06-12",
"label": "Finland",
"value": 2.88894188
}
]
}The required request parameters remain the same as for the creation of the property.
The endpoint to be used can be one of the following depending on the method:
HTTPS
- For US clients: https://api-us.kurtosys.app>/dataloader/upsertentity
- For UK clients: https://api-uk.kurtosys.app>/dataloader/upsertentity
- For EU clients: https://api-eu.kurtosys.app>/dataloader/upsertentity
Websocket (for bulk uploads)
- For US clients: wss://api-us.kurtosys.app>/dataloader/upsertentity
- For UK clients: wss://api-uk.kurtosys.app>/dataloader/upsertentity
- For EU clients: wss://api-eu.kurtosys.app>/dataloader/upsertentity
The API will respond with the below code to indicate successful creation, along with a 200 OK response code.
Load the allocation data using the API
Log in to Kurtosys App to check it has been loaded successfully
Things to keep in mind
Correcting a specific allocation’s data value:
If an error occurred during the initial loading, you can fix it by sending the entire request body again, including all the columns and rows. Only update the data values for the specific column or row that needs correction. Do not send a request body with only the specific column or row, as this will overwrite the previously loaded data.
Deleting a specific allocation’s data value:
If an allocation should no longer carry any data, you can delete the allocation.
Creation on different levels:
If data has to be loaded at both class and fund levels, the allocation data should be loaded separately at each level. This can be done by changing the ‘type’ field to the correct level. For example, ‘CLSS’ for class level, or ‘FUND’ for fund level.
Changing the client code for each product entity:
If multiple products or entities require allocation data to be loaded, make sure to change the client code field for each API request; otherwise, you will simply overwrite the same product/entity. By extension, each product or entity code must be unique.
Ensuring data loaded matches the data format:
When loading data, it is crucial to ensure that the data matches the data format of the column.
The following rules apply to each data format:
- String (STRG): The field can receive any data value but is most commonly used for text, or combinations of numbers and text.
- Decimal (DCML): The field can receive numeric values with any number of decimals. A full stop (.) must be used to indicate decimals (eg 20.50)
- Integer (ITGR): The field can also carry numeric values but cannot carry decimal numbers. (eg 40)
- Boolean (BOOL): This field is used to store true or false data values. Data values must be provided as ‘0’ or ‘1’. Zero indicates false and one indicates true.
- Date (DATE): The field can only receive and carry dates. Dates need to be formatted using the following convention: YYYY-MM-DD
- Date and Time (DTIM): The field is used to store combinations of dates and times. The following convention should be used: “YYYY-DD-MM HH:MM:SS”
Step 3: Retrieve Allocation Data
Once the allocation has been loaded you can search and retrieve various products and entities from the Kurtosys App that carry that allocation. This can be done individually or in bulk based on search criteria.
Option 1: Retrieving Allocations for an Individual Product or Entity
Retrieve a specific product or entity using a specific client code.
Required fields
Field | Required | Description | Requirements | Example |
|---|---|---|---|---|
type | Required | Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account | Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’ | FUND |
clientCode | Required | The identifier used for the product or entity. Could be any data value that identifies the product or entity. | A unique code that is used to identify and retrieve a specific product or entity. | FUND01 |
search | Required | Indicates which parameters should be included in the search. If everything should be returned, it can be included but left blank. | Must be included in the request body. Empty square brackets can be used to retrieve all data. | “search”: [ ] |
include | Required | Instructs the API to return data like allocations, statistics, timeseries, etc | Must be included if data other than properties should be returned by the API. | “include”: {} |
allocations | Required | Instructs the API to specifically include allocations data in the response. | Must be included if allocations data should be returned by the API. When brackets are left empty, the API will return all allocations that exist in the system. | “allocations”: {} |
limitTo | Optional | Allows the user to return only the allocations specified. | One or more allocations can be specified. The codes of all allocations required should be added. | “limitTo”: [“top_ten_holdings”, “country_allocation”] |
An example of retrieving specific entities with allocation data
In the following example, we have already created a couple products/entities in the system. We would now like to retrieve the allocations data for a specific product on class level. Client code: ‘GB00B4NVSH01’
{
"type": "CLSS",
"clientCode": ["GB00B4NVSH01"],
"search": [],
"include": {
"allocations": {
"limitTo": ["top_ten_holdings"]
}
}
} - For US clients: https://api-us.kurtosys.app/fund/searchEntity
- For UK clients: https://api-uk.kurtosys.app/fund/searchEntity
- For EU clients: https://api-eu.kurtosys.app/fund/searchEntity
The API will respond with the below code to indicate successful creation, along with a 200 OK response code.
{
"data": {
"entityId": 1104542,
"parentEntityId": null,
"type": "CLSS",
"clientId": 1180,
"clientCode": "GB00B4NVSH01",
"lastModified": "2024-05-27T14:06:38.000Z",
"lastModifiedBy": 3544,
"created": "2024-05-27T09:56:30.000Z",
"createdBy": 3544,
"propertiesPub": {
"inception_date": {
"value": "1994-09-30"
},
"isin": {
"value": "GB00B4NVSH01"
},
"aum": {
"value": 123000000
},
"asset_class": {
"value": "Equity"
},
"country_reg_inst": {
"value": [
"LU",
"CH"
]
}
}
"properties_draft": null,
"userProperties_pub": null,
"userProperties_draft": null,
"jobReference": "1932901b-8c5d-4a6f-90c0-5743b89a2711",
"rowHash": "beb338c4b9e567f80a0c1a43dd921e4d5b75f90f8ec46e6bc5c346fedff94b86"
}
}Log in to the Kurtosys App and review the property data within the Data module.
Option 2: Retrieve all products/entities that carry a specific allocation
Retrieve products or entities using a search for a property carrying a specific data value.
Required fields
Field | Required | Description | Requirements | Example |
|---|---|---|---|---|
type | Required | Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account | Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’ | CLSS |
search | Required | Allows the user to specify search criteria. | Contains the parameters required for the search. This includes the property, the required values, and a match type. Any number of required values can be used in the search. Two match types can be used: ‘MATCH’ for an exact match, and ‘LIKE’ for a fuzzy match. | “search”: [{
“property”: “asset_class”,
“values”: [“Equity”],
“matchtype”: “MATCH”
}], |
limit | Not Required | Allows the user to specify a limit to the number of products or entities returned. This is useful when you have a large number of results. | Must be a numeric value. | 1000 |
start | Not Required | Returns a specified subset of results. Especially useful when you have more results than the limit specified. | Must be a numeric value. ‘0’ is the first product or entity in the list. | 0 |
sort | Not Required | Allows for the sorting of search results. Can be based on the same property used for the search or another property. | Must contain two elements: ‘key’ which specifies the property used to sort. ‘direction’ which can either ascending (ASC) or descending (DESC). | ASC |
An example of retrieving entities using search rules
In the following example, we have already created a couple products/entities in the system. We would now like to retrieve the products or entities that carry the property of Asset Class with the value of ‘Equity’.
{
"type": "CLSS",
"search": [],
"include": {
"allocations": {
"limitTo": [
"top_ten_holdings"
]
}
},
"limit": 1000,
"start": 0
}- For US clients: https://api-us.kurtosys.app/fund/searchEntity
- For UK clients: https://api-uk.kurtosys.app/fund/searchEntity
- For EU clients: https://api-eu.kurtosys.app/fund/searchEntity
The API will respond with the below code to indicate successful creation, along with a 200 OK response code.
{
"values": [
{
"entityId": 1104542,
"parentEntityId": null,
"type": "CLSS",
"clientId": 1180,
"clientCode": "ABCD",
"lastModified": "2024-05-27T14:06:38.000Z",
"lastModifiedBy": 3544,
"created": "2024-05-27T09:56:30.000Z",
"createdBy": 3544,
"properties_pub": {
"asset_class": {
"value": "Equity"
},
"benchmark_name": {
"value": "S&P 500"
},
"effective_date": {
"value": "2024-05-27"
},
"fund_base_currency": {
"value": "EUR"
},
"fund_name": {
"value": "Kapital Equity Fund"
},
"isin": {
"value": "ABCD"
}
},
"properties_draft": null,
"userProperties_pub": null,
"userProperties_draft": null,
"jobReference": "1932901b-8c5d-4a6f-90c0-5743b89a2711",
"rowHash": "beb338c4b9e567f80a0c1a43dd921e4d5b75f90f8ec46e6bc5c346fedff94b86"
}
],
"total": 1,
"limit": 1000
}Use the returned API response to review the allocations data for entities