Calling the StoryTeller API
For a detailed documentation of our API parameters, please refer to our API reference documentation.
StoryTeller API offers two main endpoints, one for generating reports on funds and another for portfolios:
- Batch fund endpoint:
https://api.storyteller.investsuite.com/batch/fund/{tenant_id}/ - Batch portfolio endpoint:
https://api.storyteller.investsuite.com/batch/portfolio/{tenant_id}/
Authentication¶
The API key is provided during the account setup and should be included in a x-api-key header of every API request. The Tenant ID is a unique identifier assigned to your account and should be included at the end of the URL of every API request. Please find an example request below, where the tenant id is tenant_id and the API key api_key:
curl --location 'https://api.storyteller.dev.investsuite.com/batch/fund/<tenant_id>/' \
--header 'x-api-key: <api_key>' \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"fund_meta": {
"fund_identifier_type": "ISIN",
"fund_identifier": "GB00BYW8VG25"
}
},
"correlation_key": "fund_01"
],
"start_date": "2023-05-31",
"end_date": "2023-06-30"
}'
Response¶
If the request is succesful, the response will contain, for each requested item, the path to the folder where the report will be stored. Each report that is requested will be stored in a separate folder. To know which report is stored in what folder, you can use the correlation_key parameter to name each requested item.
If no correlation key is given
If no correlation key is specified in the input, the response will use keys corresponding to the position in the list. So if, for example, there are three items in the request body, all without a correlation key specified, the response will have three keys: "0", "1", and "2", where the value under "0" corresponds to the folder where the report of the first item in the list will be stored, and so on.
{
"fund_01": {
"destination_folder": "<path_to_folder>"
}
}
The request body¶
When making requests to the StoryTeller API, the content of the request body will varies depending on whether you are generating reports on funds or portfolios. For both endpoints, for each batch request, the start date and end date of the reports is defined globally over all items in the API request. Then, input can be given for each report to be generated as a separate item. Some parameters are the same for both the fund and portfolio endpoints, these are first described below.
Changing the language¶
If you have the option to generate reports in multiple languages, you can control the language that a report is generated in via the API input. The language parameter consists of two 2-letter codes, split by an underscore. The first code is a lowercase code for the language, and the second is an uppercase code for the country. Example language parameter values are en_GB, en_US, nl_BE and fr_FR.
{
"items" : [
{
...
"report_meta": {
"language": "en_GB"
}
}
],
...
}
Available languages
The available languages are configured per client, and are determined when your account is set up.
Default language
If no language is provided in the API input, the default language that is determined at account setup is used.
Changing the picture theme¶
If you have multiple picture themes available for your reports, you can control the theme of the pictures in the report report via the API input. The names of picture themes are specific to a tenant and are communicated once the account is set up. As an example, picture themes can be MOUNTAINS, AIR_BALLOONS, or GARDENING.
{
"items" : [
{
...
"report_meta": {
"picture_theme": "MOUNTAINS"
}
}
],
...
}
Available picture themes
The available picture themes are configured per client. The themes are determined when your account is set up, and can always be expanded with custom picture themes.
Default picture theme
If no picture theme is provided in the API input, the default picture theme that is determined at account setup is used.
Including/excluding ESG insights¶
If ESG insights are available for your reports, you can include or exclude them from a report via the API.
{
"items" : [
{
...
"report_meta": {
"requested_insights": {
"esg": {
"include": false
}
}
}
}
],
...
}
Adding a word of the expert¶
If available for your reports, you can add a "word of the expert" for each report via the API. When providing this content, the title and body fields are required. The name, role and image parameters can be specified as well. Images of the experts are added to StoryTeller on beforehand. Then, for each expert image, there is a corresponding parameter value that you can use in your API input. In the example, there is an expert called Sophie Williams who is the Chief Investment Strategist. A picture of Sophie was provided on beforehand, and that picture is specified by putting SOPHIE for the image field.
{
"items" : [
{
...
"report_meta": {
"custom_content": {
"expert": {
"name": "Sophie Williams",
"role": "Chief Investment Strategist",
"title": "The great interest reset",
"body": "Stock markets rounded off a tumultuous year with gains in Q4. Asian shares were boosted by China’s relaxation of its zero-Covid policy, while European equities also advanced strongly. Government bond yields edged up towards the end of Q4 (meaning prices fell). This reflected some market disappointment at major central banks reiterating plans to tighten monetary policy, even as inflation showed signs of peaking. Commodities gained in the quarter, led by industrial metals.Growth and inflation will still be causes for concern next year; but markets are already showing signs of a comeback. We expect that confirmation of peak inflation in Q1 2023 may lead to a pause in interest rate hikes by central banks, which would set in motion the recovery process in fixed-income markets. The recovery of more cyclical assets, like equities, should get underway in H2 2023 if central banks announce lower interest rates. More than ever, it is paramount to balance a short and long-term vision when managing investments as investors should not ignore the need to be invested in real assets and in thematics related to innovation and sustainability.",
"image": "SOPHIE"
}
}
}
}
],
...
}
Supported HTML tags word of the expert
The body text supports the following HTML tags:
<br><strong><ol><ul><li>
Fund reports¶
For generating reports on funds specifically, the request body should minimally include the fund identifier. This can be provided under the fund_meta part of the API request body:
{
"items" : [
{
...
"fund_meta": {
"fund_identifier_type": "ISIN",
"fund_identifier": "GB00BYW8VG25"
}
}
],
...
}
Portfolio reports¶
When generating portfolio reports through the StoryTeller API, next to the optional fields above, you minimally need to provide the holdings and the cumulative return timeseries. These are described below.
Holdings¶
Holdings are the specific assets within a portfolio, such as stocks or bonds. For each holding you need for each given date:
-
identifier: a unique identifier, which can be, if data needs to be fetched from third-party market data providers, an ISIN (International Securities Identification Number) or an ISO 4217 currency code. If data is not available from third-party market data providers, but custom data for the instrument is uploaded via the Financial Data API, you can use the identifier used to upload the data under. -
quantity: the quantity of the instrument within the portfolio. For example, if you would have 10 shares of the Apple stock, the quantity of instrumentUS0378331005is 10. -
valuation: the total valuation of that instrument in the portfolio, in the base currency of the portfolio. For example, if you have 3 shares of a stock that is $50 per share, the valuation for that instrument is $150 if the base currency of the portfolio is dollars.
Required dates to provide holdings
All holdings in the portfolio must at least be provided for each business day of the reporting period and the day before the reporting period, due to the reliance on end-of-day prices. All instruments in the portfolio should belong to the pre-defined investment universe. Any instruments outside of this universe may not be recognized, leading to failure to generate the report.
Let's take a simple example. If we want to generate a report for the first 3 days of January, for a portfolio that contains 2 holdings: cash in EUR and 5 shares of Apple. The start date is "2023-01-01" and the end date is "2023-01-03". The holdings for this portfolio should look like this:
{
"items" : [
{
...
"holdings": {
"2022-12-31": [
{
"identifier": {
"identifier": "EUR",
"identifier_type": "CURRENCY_ISO"
},
"quantity": 100,
"valuation": 100
},
{
"identifier": {
"identifier": "US0378331005",
"identifier_type": "ISIN"
},
"quantity": 5,
"valuation": 606.92
}
],
"2023-01-01": [
{
"identifier": {
"identifier": "EUR",
"identifier_type": "CURRENCY_ISO"
},
"quantity": 100,
"valuation": 100
},
{
"identifier": {
"identifier": "US0378331005",
"identifier_type": "ISIN"
},
"quantity": 5,
"valuation": 606.92
}
],
"2023-01-02": [
{
"identifier": {
"identifier": "EUR",
"identifier_type": "CURRENCY_ISO"
},
"quantity": 100,
"valuation": 100
},
{
"identifier": {
"identifier": "US0378331005",
"identifier_type": "ISIN"
},
"quantity": 5,
"valuation": 609.20
}
],
"2023-01-03": [
{
"identifier": {
"identifier": "EUR",
"identifier_type": "CURRENCY_ISO"
},
"quantity": 100,
"valuation": 100
},
{
"identifier": {
"identifier": "US0378331005",
"identifier_type": "ISIN"
},
"quantity": 5,
"valuation": 592.86
}
]
}
}
],
...
}
Return timeseries¶
A timeseries of the cumulative return percentage of the portfolio provides insights into the portfolio’s performance over time. When generating reports on portfolios, it is required to include this return timeseries for each report to be generated. Ideally the timeseries is provided since inception of the portfolio. Here’s what you need to include:
-
cumulative_return_pct: the timeseries itself. -
start_date_type: this describes what the first date in the timeseries is. Most of the time, because the cumulative return is since inception, this parameter will be"SINCE_INCEPTION". If not all data is available since inception, this parameter can also be"YEAR_TO_DATE","CURRENT_PERIOD", or"OTHER"for example.
Let's take a simple example again: we have a portfolio that exists since December 15th, 2022. We want to generate a report on this portfolio for January, 2023. At the end of that month, the portfolio had a return of 4%. A cumulative return timeseries could look like this:
{
"items" : [
{
...
"portfolio_meta": {
"timeseries": {
"cumulative_return_pct": {
"start_date_type": "SINCE_INCEPTION",
"timeseries": {
"2022-12-15": 0.0,
"2022-12-16": 0.0,
"2022-12-17": -0.01,
"2022-12-18": 0.0,
"2022-12-19": 0.01,
"2022-12-20": 0.01,
"2022-12-21": 0.01,
"2022-12-22": 0.01,
"2022-12-23": 0.01,
"2022-12-24": 0.02,
"2022-12-25": 0.02,
"2022-12-26": 0.02,
"2022-12-27": 0.02,
"2022-12-28": 0.02,
"2022-12-29": 0.03,
"2022-12-30": 0.02,
"2022-12-31": 0.02,
"2023-01-01": 0.02,
"2023-01-02": 0.01,
"2023-01-03": 0.02,
"2023-01-04": 0.02,
"2023-01-05": 0.02,
"2023-01-06": 0.02,
"2023-01-07": 0.03,
"2023-01-08": 0.03,
"2023-01-09": 0.03,
"2023-01-10": 0.03,
"2023-01-11": 0.03,
"2023-01-12": 0.03,
"2023-01-13": 0.04,
"2023-01-14": 0.04,
"2023-01-15": 0.04,
"2023-01-16": 0.04,
"2023-01-17": 0.03,
"2023-01-18": 0.03,
"2023-01-19": 0.04,
"2023-01-20": 0.04,
"2023-01-21": 0.04,
"2023-01-22": 0.04,
"2023-01-23": 0.04,
"2023-01-24": 0.05,
"2023-01-25": 0.05,
"2023-01-26": 0.05,
"2023-01-27": 0.05,
"2023-01-28": 0.04,
"2023-01-29": 0.04,
"2023-01-30": 0.04,
"2023-01-31": 0.04
}
}
}
}
}
],
...
}
Providing specific numbers in a given period¶
When generating reports, there may be instances where you need to provide specific data for a given period, such as the return percentage, return value, cash flow data, .. . This can be done by using the portfolio_meta.since_date_info field.
Let's say you want to provide the return value since the start of the portfolio (€5000), the amount withdrawn during the reporting period (€1000), and the amount deposited during the reporting period (€4000). The portfolio exists since March 7th, 2022 and the report is on January, 2023. The since_date_info part of the API input would look like this:
{
"items" : [
{
...
"portfolio_meta": {
"since_date_info": {
"since_inception": {
"start_date": "2022-03-07",
"return_value": 5000
},
"since_current_period": {
"start_date": "2023-01-01",
"total_withdrawals": 1000,
"total_deposits": 4000
}
}
}
}
],
...
}