Contents x
    Qualitative Data Access APIs
        Contents

        Qualitative Data Access APIs

            Article summary

            Assette Qualitative Data Access API - Documentation

            Background

            This document outlines the APIs that our clients can use to retrieve qualitative data stored in Assette Client Database.

            Introduction

            Assette application is designed to retrieve data from different sources, combine and transform them if needed and consume them to generate different types of contents such as PDF, PowerPoint, Word, Excel, client portal web pages, etc. In addition to that, Assette application also supports entering and storing qualitative data required to enable automatic content generation such as narratives, disclosures, investment explanations, index descriptions, etc.

            Assette Data Access APIs are designed to support.

            • Exposing qualitative data managed and stored within Assette (discussed in this document).

            • Expose the output of any data block – this can contain data obtained from different sources, combined, and processed within Assette.

            Qualitative Data

            Qualitative data APIs expose below data categories,

            • Narratives – This includes firm level, strategy level, product level and people level data.

            • Disclosures – Disclosure messages that are constructed by conditionally combining disclosure fragments.

            • Investment Explanations – Investment explanations on purchase and sales rational, sector rational, country rational, etc., and special firm level and strategy level investment explanation blocks.

            • Index Descriptions – List of indexes and their descriptions

            Security

            The clients can choose any combination of authentication mechanisms given below. Assette can securely expose these APIs.

            • Client certificates authentication (two-way SSL authentication)

            • OAuth 2 authentication (client credentials grant flow)

            • Authorization Key

            • Client IP Whitelisting

            Assette Data Access API

            API to query for data as a list of records:

            Return output as a list of records.

            Method: POST

            Path: /qdata/{{data_category}}/list_queries

            URL Parameters:

            • data_category – the data category

            Message Body:

            {

            "dataSet": "{{data set}}",

            "fields": ["{{field 1}}", "{{field 2}}", "{{field 3}}"],

            "filters": {

            "{{parameter 1 name}}": "{{parameter 1 value}}",

            "{{parameter 2 name}}": "{{parameter 2.1 value}}, {{parameter 2.2 value}}",

            "{{parameter 3 name}}": "{{parameter 3 value}}"

            },

            "parameters": {

            "{{parameter 1 name}}": "{{parameter 1 value}}",

            "{{parameter 2 name}}": "{{parameter 2 value}}",

            "{{parameter 3 name}}": "{{parameter 3 value}}"

            }

            }

            Response:

            {

            "success": true,

            "data": [

            {"field 1": value1, "field 1": value1, "field 3": value3},

            {"field 1": value1, "field 1": value1, "field 3": value3}

            ]

            }

            Sample Request:

            POST https://api.assette.com/qdata/narratives/list_queries

            {

            "dataSet": "people",

            "fields": ["code", "firstName", "lastName", "gender"],

            "filters ": {

            "primaryJobFunction": "Client Service Manager"

            },

            "parameters": {

            "asOfDate": "12-31-2023"

            }

            }

            API to query for data as a single text value:

            Return output as a single text value. Text query would work for narratives, investment explanations and special lists, only if the parameters and filters result in single record output.

            Method: POST

            Path: /qdata/{{data_category}}/text_queries

            URL Parameters:

            • data_category – the data category

            Message Body:

            {

            "dataSet": "{{data set}}",

            "field": "{{field}}",

            "parameters": {

            "{{parameter 1 name}}": "{{parameter 1 value}}",

            "{{parameter 2 name}}": "{{parameter 2 value}}",

            "{{parameter 3 name}}": "{{parameter 3 value}}"

            }

            }

            Response:

            {

            "success": true,

            "text": "text value"

            }

            Sample Request:

            POST https://api.assette.com/qdata/narratives/text_queries

            {

            "dataSet": "Strategy-GeneralInfo",

            "field": "detailedStrategyOverview",

            "parameters": {

            "AccountCode": "C001"

            }

            }

            POST https://api.assette.com/qdata/disclosures/text_queries

            {

            "dataSet": "Disclosure1",

            "parameters": {

            "AccountCode": "C001",

            "AsOfDate": "12-31-2023"

            }

            }

            Query Parameters

            Supported Data Categories:

            • narratives

            • narrative-metadata (support list queries only)

            • disclosures (support text queries only)

            • investment-explanations

            • special-lists – special lists such as “index-descriptions”

            Data Set:

            The name of the data set (please refer to the Data Sets section for a list of supported data sets).

            Fields:

            List of fields that should be included in the output (please refer to the Field Names section to see more details on how to obtain these field names). This parameter is only applicable for list queries on narratives and special lists.

            Field:

            The value of the field that should be included in the output (please refer to the Field Names section to see more details on how to obtain these field names). This parameter is only applicable for text queries on narratives and special lists.

            Filters:

            This parameter is only applicable for list queries on narratives. It expects a set of field name-values pairs (please refer to the Field Names section to see more details on how to obtain these field names). It is possible to provide a single value, or a comma separated list of values as filters.

            Parameters:

            The applicable parameters depend on the data set (please refer to the Parameters section for details).

            Field Names

            This list of fields supported by each narrative data set can be obtained using the request below.

            POST https://api.assette.com/qdata/narrative-metadata/list_queries

            {

            "dataSet": "{{data set}}"

            }

            E.g.

            POST https://api.assette.com/qdata/narrative-metadata/list_queries

            {

            "dataSet": "people"

            }

            Data Sets

            It is possible to get the list of supported data sets for each data category by sending a query with dataset name left blank.

            E.g.

            Query to list all disclosures.

            POST https://api.assette.com/qdata/disclosures/list_queries

            {

            "dataSet": ""

            }

            Query to list all supported narrative data sets.

            POST https://api.assette.com/qdata/narratives/list_queries

            {

            "dataSet": ""

            }

            Parameters

            The required and supported parameters that need to be passed depend on the data category and data set.

            Narratives:

            • AsOfDate – this is an optional parameter supported by all narratives to retrieve the narrative values as of a given date. If this parameter is not provided, the data will be returned as of today.

            • AccountCode – this is a required parameter for text queries and optional parameter for list queries on all strategy-based data sets. This parameter is used to filter the data by the strategy of that account.

            Disclosure:

            • AccountCode – This parameter is used to conditionally construct disclosures based on account attributes.

            Disclosures may include any other parameter such as country, purpose, etc. if they are required for the conditions.

            Note: disclosures only support text queries, when data set name is not empty.

            Investment Explanations

            Investment explanations support below parameters,

            • AccountCode – this is a required parameter for all strategy level investment explanations. This parameter is used to filter the data by the strategy of that account.

            • AsOfDate – this is a required parameter. Investment explanations are always provided against a specific as of date.

            • Period - this is a required parameter. Investment explanations are always provided against a specific period.

            • BlockName – this is a required parameter for all text queries on global-blocks and strategy-blocks data sets.

            Note: Investment explanations support text queries only for global-blocks and strategy-blocks data sets.

            Special Lists

            No parameters needed.

            Currently Supported Narrative Data Sets

            Firms

            • Firms-Administrative

            • Firms-Compliance

            • Firms-ESG

            • Firms-GeneralInfo

            • Firms-Investment

            • Firms-RiskManagement

            • Firms-Trading

            • Firms-ClientService

            • Firms-Research

            • Firms-Product

            • Firms-Teams

            Strategy

            • Strategy-Administrative

            • Strategy-Compliance

            • Strategy-EsgPolicy

            • Strategy-GeneralInfo

            • Strategy-Investment

            • Strategy-Marketing

            • Strategy-RemunerationAndBonus

            • Strategy-Technology

            • Strategy-TradeOrganizations

            • Strategy-ServiceProviders

            • Strategy-BiosToDisplay

            • Strategy-CyberSecurity

            • Strategy-Regulatory

            • Strategy-LegalIssues

            • Strategy-OwnershipPolicies

            • Strategy-KeyPersonnel

            • Strategy-InvestmentProfessionals

            • Strategy-Teams

            People

            • People

            Ownership

            • Ownership

            Currently Supported Investment Explanation Data Sets

            • Global-Blocks

            • Strategy-Blocks

            • Purchas-and-Sells-Rational

            • Sector-Rational

            • Industry-Rational

            • Region-Rational

            • Country-Rational

            • Holdings-Rational

            Special List Data Sets

            • Index-Descriptions

            Error Responses

            If there is a validation error then the response would be in below format,

            Status Code: 400

            Output:

            {

            "success": false,

            "message": "the validation error"

            }

            If there is a server-side error, then the response would be in below format,

            Status Code: 500

            Output:

            {

            "success": false,

            "message": "the error message"

            }

            What's Next