Entity Search Service

The entity search service is the most important service involved in building out our client's fund tools! It is structured like a one stop shop / swiss army knife. It allows you to:

The following endpoints are supported

Endpoint Method Description
/searchEntity POST Search for entities such as Classes, Funds and Accounts
/getEntity POST Retrieve a specific entity
/fundmanagerpicture GET Get a Fund Manager's picture
/getfilters POST Return all the distinct values for the specified entity properties
/getfacets POST Returns entity properties with the value containing a search term
/searchCodes POST Returns a list of entity codes you are allowed to see
/searchEntityFundlist POST Returns a list of entity codes and fund list names

Search Entities

You can make use of this endpoint to get a list of entities, with various other related data. Keep in mind if you have data entitlements enabled, your results will be limited.

Parameter Value
End Point https://api.fundpress.io/fund/searchentity
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON

Here is a complete schema of the body, bellow we explain what each property does

{
    "type": "CLSS",
    "fundList": "intermediaries_LU",
    "fundListExclusion": ["exclude_a_segment"],
    "includeProperties": ["admin_fee", "bloomberg_code"],
    "applyFormats": true,
    "culture": "en-GB",
    "sourceCulture": "fr-FR",
    "translate": true,
    "preserveOriginal": true,
    "disclaimers": true,
    "clientCode": ["KS1234567890", "KS1234567891"],
    "identifierSearch": {
        "properties": [
            "isin",
            "fund_name"
        ],
        "value": "LU1",
        "fuzzy": false
    },
    "search": [{
        "property": "share_class",
        "values": ["EB"],
        "matchtype": "MATCH"
    }],
    "sort": {
        "key": "asset_class",
        "direction": "ASC"
    },
    "advancedSort": {
        "type": "Statistics" | "Allocations";
        "code": string;
        "key": string;
        "value": string;
        "direction": "ASC" | "DESC";
    },
    "include": {
        "timeseries": {
            "limitTo": ["prices"]
        },
        "allocations": {},
        "fundManagers": {},
        "statistics": {},
        "commentaries": {},
        "disclaimers": {},
        "documents": {
            "joinSpec": [{
                "joinTo": "isin",
                "search": [{
                    "property": "document_type",
                    "matchtype": "MATCH",
                    "values": ["Factsheet", "KIID"]
                }]
            }]
        }
    },
    "limit": 10,
    "start": 0
}

Required Properties

"type": "CLSS",
"search": []

The type determines what type of entity you are searching for. Each entity has an type of either CLSS, FUND, BMRK or ACCT. The most common are CLSS (for a share class) and FUND for a fund.

The search property is explained in more depth bellow. Make use of it to filter down your results. Leaving it empty won't filter on any properties.

Search

The options below allow you to filter results. Note that they all can operate in tandem, but when combined they operate as AND. That is, the only results returned will be ones that fulfill all the clauses provided.

"search": [{
    "property": "share_class",
    "values": ["EB"],
    "matchtype": "MATCH"
}],

The search block allows you to construct more complex search terms against the data stored against an entity. The search is an array of terms, which are combined together as an AND. Each term has a property (chosen from the properties_pub property of the entity), an array of values (a match on any of which will return true for that property, an in clause essentially) and a matchtype. The match can be MATCH (for a direct match) or LIKE (for a SQL like).

Field Search

Certain fields are also searchable using the same search fields as properties. Instead of using the property name in the search object, use the entity's field name instead. Only the clientCode is currently supported, for example:

"search": [{
    "property": "clientCode",
    "values": [ "KS1" ],
    "matchtype": "LIKE"
}]

Identifier Search

"identifierSearch": {
    "properties": ["isin", "fund_name"],
    "value": "LU1",
    "fuzzy": false
}

The identifier search can be used to implement a 'full text search' on properties. You pass an array of approved property names, and a single value. It will perform a like match on all of them and return results that are true in any of the fields provided. In that sense the search operates as an OR across each of the fields. Adding fuzzy:true will make the search match any token in the string you provide.

Fund lists

N.B. You need to setup a fund list first to be able to use these filters.

"fundList": "intermediaries_LU"

Often our client's sites will gate content from people until they identify as an investor from a certain region and of a certain class (institutional, individual, intermediary, etc…). Often this will mean certain products are not appropriate for them. Fund Lists allow the client to maintain these white lists. Passing the name of one here will pre-filter the results prior to pagination. Its a nice clean way of implementing this functionality!

"fundListExclusion": "exclude_a_segment"

Sometimes a client would like to specify that some entities should be excluded from being displayed. To do this we can create a list of these entities and add it to the search as above.

Both the fundList and fundListExclusion can be set to a string or an array of strings. If an entity is found in both the inclusion and exclusion fundLists then it will exclude the entity.

Client Code

The clientCode property will limit the search to only the entities with the clientCodes provided.

Include Properties

If includeProperties is set as empty, i.e. to an empty array, it will remove the properties_pub property from the entity results.

By specifying the included properties as bellow

"includeProperties": ["admin_fee", "bloomberg_code"]

It will only include the specified properties in the properties_pub.

Include relevant data

"include": {
     "timeseries": {
        "limitTo": ["prices"]
    },
    "allocations": {},
    "fundManagers": {},
    "statistics": {},
    "commentaries": {},
    "disclaimers": {},
    "documents": {
        "joinSpec": [{
            "joinTo": "isin",
            "search": [{
                "property": "document_type",
                "matchtype": "MATCH",
                "values": ["Factsheet", "KIID"]
            }]
        }]
    }
}

The include object allows you to add more related data to the response. This saves time and precious requests when building a complex page. Each linked data type can be retrieved by passing a key and an object as above. For timeseries, allocations, and statistics, a limitTo key can be passed. This takes the form of a string array, with each value representing a code for the data set you wish to retrieve.

For documents the way in which entities and documents are associated is loose. Therefore we provide a syntax for providing a join. The joinTo field specifies a piece of meta data on the document to match the entities client code against. The entities client code is effectively a primary key of each entity, unique for that client. The key to this functionality is of course that a field exists on the document that mirrors the entities client code. If required, a joinFrom can be provided that can specify a target property to be used instead of the client code of the fund or share class.

You can filter the included documents by supplying the optional search property to the joinSpec. This is equivalent to how you would search documents in general. This payload will find documents who's isin meta property equals the entity's clientCode, it will then further filter down documents with the meta property of document_type that equals Factsheet OR KIID.

Apply Formats

Different cultures over the world have different requirements and standards. E.g. Culture X might have different date formats, currencies, languages etc, than culture Y. We are able to change the format of an entity's values by making use of the properties below.

"culture": "fr-FR"

A culture code used to look up region specific formats and translations.

"sourceCulture": "en-GB"

The source culture that the data is stored as in the system.

"translate": true

If specified the service will load a dictionary into the response and attempt to translate the available words.

"preserveOriginal": true

This will append the original value as originalValue to the entity before formatting it.

"disclaimers": true

If specified the system will attempt to attach disclaimers to certain data points. This functionality relies on each property being tagged with a disclaimer type to link the two pieces of data.

"applyFormats": true

If specified the system will attempt to apply format codes to data on the server side. This functionality relies on each property being tagged with a format code to link the two pieces of data.

Sorting

The sort accepts an object, or an array of objects

"sort": {
    "key": "asset_class",
    "direction": "ASC"
}

or

"sort": [
    {
        "key": "asset_class",
        "direction": "ASC"
    },
    {
        "key": "bloomberg_code",
        "direction": "ASC"
    }
]

If an array is passed, the sort objects are processed in order. The sort object specifies a property to sort on (the key) and the direction (ASC or DESC).

Advance Sorting

"advancedSort": {
    "type": "Allocations",
    "code": "country_allocation",
    "key": "Hong Kong",
    "value": "net",
    "direction": "DESC"
}

Instead of the sort object, the advancedSort allows sorting Statistics or Allocations, using the code to identify which data set, key to identify a particular label within the data set, and which value to sort by. If the value is not supplied then it would default to the value property. The sort order defaults to ASC but can be overridden by using the direction property.

Pagination

"limit": 10,
"start": 0

limit specifies the number of entities to return, while the start specifies the index at which the objects will be returned from.

Get Entity

Retrieves a specific entity by clientCode

Parameter Value
End Point https://api.fundpress.io/fund/getEntity
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "type": "CLSS",
    "clientCode": "UNIQUE_IDENTIFIER",
    "include": {
        "timeseries": {},
        "allocations": {},
        "statistics": {}
    }
}
Property Required Description
type TRUE The entity type
clientCode TRUE The unique identifier for the entity
include FALSE Opt-in to retrieving data for the entity. Limited to all timeseries, allocations and statistics associated with this entity

Fund Manager Picture

Returns a Fund Manager's picture. Note that this is a GET request that requires the Fund Manager code and a token.

Parameter Value
End Point https://api.fundpress.io/fund/fundmanagerpicture?code={{code}}&token={{token}}
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method GET
Return Type As specified in the database

Get Filters

This would allow you to list all possible property value options for entity meta properties. Take the example below, it will query all the possible property/tag values for entities with the tags of ccy, citi_code, class_code and distribution_type. It will also further filter down if you supply it with a search clause. Keep in mind, if you have data entitlements enabled, it will filter your results based on your entitlement configuration.

Parameter Value
End Point https://api.fundpress.io/fund/getfilters
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "type": "CLSS",
    "fundList": ["professional_SE"],
    "fundListExclusion": ["UK Advisor"],
    "filterProperties": ["ccy", "citi_code", "class_code", "distribution_type"],
    "search": [
        {
            "property": "ccy",
            "values": ["USD"],
            "matchtype": "MATCH"
        }
    ],
    "translation": {
        "sourceCulture": "it-IT",
        "culture": "en-GB"
    }
}

An optional translation config can be included which will modify the label's of the returned values when available. sourceCulture corresponds to the culture specified to be the default culture and culture is the requested translation. Any values that don't have a corresponding translation will be returned unmodified.

{
    "type": "CLSS",
    "filterProperties": ["ccy", "citi_code", "class_code", "distribution_type"],
    "translation": {
        "sourceCulture": "it-IT",
        "culture": "en-GB"
    }
}
Property Required Description
type TRUE Filter on the entity type
filterProperties TRUE The entity properties you wish to have values returned
fundList FALSE Includes the entities in the specified fund lists
fundListExclusion FALSE Excludes the entities in the specified fund lists
translation FALSE An array of facets
search FALSE An array of strings that will be matched against the configuration

The above query will scan all your entities and return a listing of the various meta values for the ccy, citi_code, class_code and distribution_type property.

If a property is not valid document meta then it will be returned with an empty array.

{
    "ccy": [
        {
            "label": "na",
            "value": "GBP"
        },
        {
            "label": "na",
            "value": ["ZAR", "USD"]
        }
    ],
    "citi_code": [
        {
            "label": "na",
            "value": "CT124"
        },
        {
            "label": "na",
            "value": "CT124d323"
        }
    ],
    "class_code": [],
    "distribution_type": []
}

Get Facets

Facets are a list of entities meta properties filtered by a searchTerm. Only properties of STRG (string) type gets returned. Results are grouped by property key and limited to 10 results per propertyValues.

Parameter Value
End Point https://api.fundpress.io/fund/getfacets
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "entityType": "CLSS",
    "searchTerm": "USD",
    "clientCode": ["KS1234567890"]
}
Property Required Description
entityType TRUE Filter on the entity type
searchTerm TRUE An value of a entity property
clientCode FALSE An array of client codes to limit this facet search to

An example of the results based on the query above

[
    {
        property: "Currency",
        propertyValues: [
            {
                propertyValue: "USD",
                property: "Currency",
                code: "ccy",
            },
        ],
    },
    {
        property: "Long Name",
        propertyValues: [
            {
                propertyValue: "KSYS ALPHA-A-USD-FD",
                property: "Long Name",
                code: "long_name",
            },
            {
                propertyValue: "KSYS ALPHA-B-USD-FD",
                property: "Long Name",
                code: "long_name",
            },
        ],
    },
];

Search Codes

Returns a list of entity codes you are allowed to see. This is mainly used for UI auto completion. You can filter the results by a search term. Keep in mind if you have data entitlements enabled, you will only see a limited amount of client codes.

Parameter Value
End Point https://api.fundpress.io/fund/searchCodes
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "entityType": "CLSS",
    "code": "KS13"
}
Property Required Description
entityType FALSE Optional, filter on the entity type
code FALSE Filter entity codes by a search term

An example of the results based on the query above

["KS1343908234", "KS1390743943", "KS1393234367", "KS1394743985"];

Search Entity Fund List

Returns a list of entity codes and fund list names you are allowed to see. This is mainly used for UI auto completion. You can filter the results by a search term. Keep in mind if you have data entitlements enabled, you will only see a limited amount of client codes.

Parameter Value
End Point https://api.fundpress.io/fund/searchEntityFundlist
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "code": "UK"
}
Property Required Description
code FALSE Filter entity codes by a search term

An example of the results based on the query above

[
    {
        code: "UK0943338144",
        source: "Entity",
    },
    {
        code: "UK1017297455",
        source: "Entity",
    },
    {
        code: "UK Advisor",
        source: "FundList",
    },
    {
        code: "UK Individual",
        source: "FundList",
    },
    {
        code: "UK Institutional",
        source: "FundList",
    },
];

Update Saved Search Entity

This endpoint is used to upsert a saved search entity, The key, name and a valid searchEntity request body is required.

Parameter Value
End Point https://api.fundpress.io/fund/upsertSavedSearchEntity
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON

Notes regarding validating schema: Using placeholder strings for string props will be handled as is since the validation schema will still function correctly. When dealing with properties of different types, the best result will be to specify the default value and provide a dot notation string path for the input. The key is still required to map up to the key which is passed when executing the Saved Search Entity

{
    {
        savedSearchEntityKey: "defaultShareClass",
        name: "Default Share Class Request",
        description: "The default share class request used on the apps",
        body: {
            type: "CLSS",
            applyFormats: true,
            search: [{
                property: "isin",
                values: ["{isin}"],
                matchtype: "MATCH"
            }],
            include: {
                allocations: {},
                statistics: {},
                commentaries: {},
                disclaimers: {}
            }
        },
        inputs: [
            {
                key: "isin",
                label: "ISIN",
                dataType: "STRG",
                isArray: true
            },
            {
                key: "applyFormats",
                label: "Apply Formats",
                dataType: "BOOL",
                path: "applyFormats"
            }
        ]
    }
}
Property Required Description
savedSearchEntityKey TRUE The unique key per client
name TRUE The display name
description FALSE A useful description for what is being saved
body TRUE The request body, same as searchEntity
inputs FALSE The mapping of inputs in the request body

Inputs | Property | Required | Description | | -------------------- | -------- | --------------------------------------------------------------------------------------------------- | | key | TRUE | The key used for mapping a string input to the query param | | label | FALSE | The display name | | dataType | TRUE | Specify the data type of the property (STRG, BOOL, ITGR, DCML) | | isArray | FALSE | Identifies if the property being mapped is an array | | path | FALSE | The mapping of inputs in the request body. This is required when dealing with types other than STRG |

Delete Saved Search Entity

Used to delete an existing Saved Search Entity using the savedSearchEntityKey or savedSearchEntityId

Parameter Value
End Point https://api.fundpress.io/fund/deleteSavedSearchEntity
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method POST
Return Type JSON
{
    "savedSearchEntitykey": "defaultSavedSearchEntity"
}

or

{
    "savedSearchEntityId": 441
}
Property Required Description
savedSearchEntityKey FALSE The unique key per client
savedSearchEntityId FALSE The unique id

List Saved Search Entity

Returns a list of Saved Search Entities without the respective request bodies.

Parameter Value
End Point https://api.fundpress.io/fund/listSavedSearchEntities
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method GET
Return Type JSON

An example of the results based on the query above

{
    savedSearchEntities: [
        {
            savedSearchEntityId: 441,
            clientId: 955,
            name: "Saved Search Entity 1",
            savedSearchEntityKey: "savedSearchEntity1",
            description: null,
            lastModified: "2020-01-28T12:08:23.000Z",
            lastModifiedBy: 955,
            created: "2020-01-28T12:08:23.000Z",
            createdBy: 955,
        },
        {
            savedSearchEntityId: 442,
            clientId: 955,
            name: "Saved Search Entity 2",
            savedSearchEntityKey: "savedSearchEntity2",
            description: null,
            lastModified: "2020-01-28T12:08:23.000Z",
            lastModifiedBy: 955,
            created: "2020-01-28T12:08:23.000Z",
            createdBy: 955,
        },
    ];
}

Get Saved Search Entity

Returns a single Saved Search Entities with the searchEntity body.

Parameter Value
End Point https://api.fundpress.io/fund/getSavedSearchEntity/{savedSearchEntityKey}
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method GET
Return Type JSON

An example of the results based on the query above

{
    savedSearchEntityId: 454,
    clientId: 961,
    savedSearchEntityKey: 'defaultSavedSearchEntity',
    name: 'Default Saved Search Entity',
    description: null,
    body: {
        type: "CLSS",
        applyFormats: true,
        search: [{
            property: "isin",
            values: ["{isin}"],
            matchtype: "MATCH"
        }],
        include: {
            allocations: {},
            statistics: {},
            commentaries: {},
            disclaimers: {}
        }
    },
    inputs: [
        {
            key: "isin",
            label: "ISIN",
            dataType: "STRG",
            isArray: true
        }
    ],
    lastModified: '2020-01-28T12:27:36.000Z',
    lastModifiedBy: 961,
    created: '2020-01-28T12:27:36.000Z',
    createdBy: 961
}

Execute Saved Search Entity

Used to execute the Saved Search Entity and return the saved search entity result set.

Parameter Value
End Point https://api.fundpress.io/fund/savedSearchEntity/{savedSearchEntityKey}?{inputs}
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method GET
Return Type JSON

An example of the results based on the query above

{
    entityId: 10962,
    parentEntityId: null,
    type: "FUND",
    clientId: 1151,
    clientCode: "BOND",
    lastModified: "2020-01-30T10:13:58.000Z",
    lastModifiedBy: 1151,
    created: "2020-01-30T10:13:58.000Z",
    createdBy: 1151,
    properties_pub: {
        fund_code: {
            value: "BOND"
        },
        fund_name: {
            value: "Kurtosys Bond Fund"
        }
    },
    properties_draft: null,
    userProperties_pub: null,
    userProperties_draft: null,
    jobReference: "26afac34-8590-48c6-bcf6-3b214066e724",
    rowHash: "4d00915d9cec91c5e1134eb2c51cd5ae0d50f060d254b7512b20d836af9bda9f"
}

Validate Saved Search Entity

Used to validate a saved search entity with the inputs query parameters. The returned result will be the parsed saved search entity body that can be requested against the searchEntity API endpoint.

Parameter Value
End Point https://api.fundpress.io/fund/validateSavedSearchEntity/{savedSearchEntityKey}?{inputs}
Headers X-KSYS-TOKEN
Content Type application/json
HTTP Method GET
Return Type JSON

An example of the results based on the query above

{
    type: "CLSS",
        applyFormats: true,
        search: [{
            property: "isin",
            values: ["KS1319692791"],
            matchtype: "MATCH"
        }],
        include: {
            allocations: {},
            statistics: {},
            commentaries: {},
            disclaimers: {}
        }
}