Document Search and Retrieval

Documents can be searched for via meta data, listed, and then retrieved, either from the Kurtosys system directly, or from another remote source.

Searching for and Listing Documents

Specify a query to match on meta data, specify sorting order, as well as pagination results. To search for documents, post the following body to the below endpoint.

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

This will return all documents. Depending on how many documents you have, you may find that the response is too big. In this case, you may want to use paging. To do so you can add a limit and start to the query.

{
    "type": "CLSS",
    "search": [],
    "limit": 100,
    "start": 0
}

To sort the list by a tag indicating the fund or share class name, add a sort block. A sort block contains a key which targets a particular piece of meta data, and a direction, which can either be ASC or DESC.

{
    "type": "CLSS",
    "search": [],
    "sort": { "key": "fund_name", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

Search by filling in the empty search block with an array of search terms. Each search term contains a property, which should match a meta data property in the system. matchtype can either be MATCH, for an exact match, or LIKE, for an in-string match. values are the array of values that the defined property should match on. Note: if you provide more than one value, any documents that match any of the provided values will be returned. So in the example below, both KIID and Factsheet documents will be returned.

{
    "type": "CLSS",
    "search": [
        {
            "property": "document_type",
            "matchtype": "MATCH",
            "values": ["KIID", "Factsheet"]
        }
    ],
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

Searching for documents that fall within a specific date range can be achieved by specifying the matchType as RANGE and providing a start and end date in the values array. The first and second values are used as the lower and upper bounds respectively.

{
    "type": "CLSS",
    "search": [
        {
            "property": "document_date",
            "matchtype": "RANGE",
            "values": ["2017-01-01T00:00:00Z", "2017-12-31T23:59:59.999Z"]
        }
    ],
    "limit": 100,
    "start": 0
}

It is also possible to filter by the created or lastModified dates by adding a "meta": false to the search object.

{
    "type": "CLSS",
    "search": [
        {
            "property": "lastModified",
            "matchtype": "RANGE",
            "meta": false,
            "values": ["2017-01-01T00:00:00Z", "2017-12-31T23:59:59.999Z"]
        }
    ],
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

If you provide multiple search terms, only items that match both terms will be returned. So in the example below, only items marked with their document_type as KIID and with an isin of GB123123123 will be returned.

{
    "type": "CLSS",
    "search": [
        {
            "property": "document_type",
            "matchtype": "MATCH",
            "values": ["KIID"]
        },
        {
            "property": "isin",
            "matchtype": "MATCH",
            "values": ["GB123123123"]
        }
    ],
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

If a null search term is provided, documents that don't have the specified meta data property will be returned. The null search term is only supported when using the matchtype: MATCH.

In the example below, items will be returned that don't have an active meta data property (i.e. the value is null) and/or items have an active meta data property that is set to false.

{
    "type": "CLSS",
    "search": [
        {
            "property": "active",
            "matchtype": "MATCH",
            "values": ["false", null]
        }
    ],
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

You can also search for documents using their filename. This works in conjunction with the rest of the search filters.

To include the entity data as part of the search document request, provide an entity join specification as highlighted below.

Each join specification should specify the entity type of the entity and the meta property that contains the entity client code.

{
    "type": "CLSS",
    "search": [
        {
            "property": "document_type",
            "matchtype": "MATCH",
            "values": ["KIID"]
        }
    ],
    "include": {
        "entity": {
            "joinSpecs": [
                {
                    "entityType": "CLSS",
                    "joinFrom": "umbrella"
                },
                {
                    "entityType": "CLSS",
                    "joinFrom": "isin"
                },
                {
                    "entityType": "FUND",
                    "joinFrom": "fund_code"
                }
            ]
        }
    }
}

In the joinSpecs, a joinTo field can be passed to target a property on an entity, if no joinTo is provided then it will link the entities by their clientCode.

Due to performance concerns, the response will have an entities key along with a joinMap to prevent duplicate entities in the response and to reduce the size of the response.

The joinMap will have the document clientCode as the key, then will have an array of the entityIds that the document associates to. Please the example below.

{
    "total": 1,
    "values": [
        {
            "documentId": 12345,
            "clientId": 123,
            "clientCode": "MyDocType-KS1319692791-en-GB",
            "title": "Kurtosys Bond R CHF H Acc",
            "fileType": "application/pdf",
            "cultureCode": "en-GB",
            "URL": "{GUID}/docstorage/{GUID}",
            "storagePath": "{GUID}/docstorage/{GUID}",
            "thumbNailPath": null,
            "meta": {
                "document_date": {
                    "value": "{date}"
                },
                "document_type": {
                    "value": "MyDocType"
                },
                "umbrella_code": {
                    "value": "KURTOSYS"
                },
                "fund_code": {
                    "value": "BOND"
                },
                "isin": {
                    "value": "KS1319692791"
                }
            },
            "lastModified": "{date}",
            "lastModifiedBy": 123,
            "created": "{date}",
            "createdBy": 123,
            "fileSize": 46696,
            "active": 1,
            "expires": "0000-00-00 00:00:00",
            "docHash": "{HASH}",
            "filename": "MyDocType-KS1319692791-en-GB.pdf",
            "clientHosted": 0,
            "rowHash": "{HASH}",
            "inferred": {}
        }
    ],
    "joinMap": {
        "MyDocType-KS1319692791-en-GB": [1, 2, 3]
    },
    "entities": {
        "1": {
            "clientCode": "KURTOSYS",
            "entityId": 1,
            "type": "FUND",
            "properties_pub": {
                "umbrella_code": {
                    "value": "KURTOSYS"
                }
            }
        },
        "2": {
            "clientCode": "BOND",
            "entityId": 2,
            "type": "FUND",
            "properties_pub": {
                "fund_code": {
                    "value": "BOND"
                },
                "umbrella_code": {
                    "value": "KURTOSYS"
                }
            }
        },
        "3": {
            "clientCode": "KS1319692791",
            "entityId": 3,
            "type": "CLSS",
            "properties_pub": {
                "fund_code": {
                    "value": "BOND"
                },
                "isin": {
                    "value": "KS1319692791"
                },
                "short_name": {
                    "value": "R CHF H Acc"
                },
                "umbrella_code": {
                    "value": "KURTOSYS"
                }
            }
        }
    },
    "limit": 1,
    "start": 0
}

Note the joinMap will be built up based on the document meta data, there is a possibility that the joinMap will contain entities keys that is not included in the entities response key. It is recommended to first check if that key exists before accessing the entity data.

When a documentSearch includes either an entitySearch or entity targeted identifierSearches, these search values will be applied to the entity values that are returned from the entity include. This ensures that the entity data returned is consistent with the search body. In such a case, it is advisable to match the joinSpecs to the client configuration for document_to_entity_search_conf.

searchEntityRequest

A search entity request can be used to find the linked documents based on entity search results. Adding this field will fire a searchEntity request and return a list of entities which will then be matched against documents. All options available for the searchEntity request are given here, allowing the use of segmentation lists etc. to filter the document results.

{
    "type": "CLSS",
    "search": [],
    "searchEntityRequest": {
        "type": "CLSS",
        "fundList": "intermediaries_LU",
        "fundListExclusion": ["exclude_a_segment"],
        "search": [
            {
                "property": "share_class",
                "values": ["EB"],
                "matchtype": "MATCH"
            }
        ]
    },
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0
}

Exclude expired documents

If a document has been uploaded with an expires date value, the excludeExpired flag can be used to filter out any documents where the date is less than todays date. Documents that do not have an expires value will be included in the response as they have no expiry.

{
    "type": "CLSS",
    "search": [
        {
            "property": "document_type",
            "matchtype": "MATCH",
            "values": ["KIID", "Factsheet"]
        }
    ],
    "sort": { "key": "document_type", "direction": "ASC" },
    "limit": 100,
    "start": 0,
    "excludeExpired": true
}

Retrieving Documents

Once a document has been located, the file behind it can be downloaded in a number of different ways: a post, a get, as a single file, or multiple files bundled into a zip.

To retrieve a single document, pass the unique clientCode that identifies the document. Note: you can find the clientCode on each document returned from /searchDocument or attached to a fund or share class in /searchEntity.

An optional filename can also be specified to allow the file name saved with the document to be overwritten when downloaded.

If the client has created a "pardotconfig" Client Configuration and that config is enabled=true then the retrieving of any document will make a call to Pardot to log the document's retrieval provided the document request has the correct Pardot visitorid cookie (i.e. visitor_id1756).

{
    "clientCode": "asdfasdf",
    "filename": "myfile.txt"
}

Single files can be delivered inline, for instance if you want to put them into an <img> tag or an <iframe>. To do this, add inline=true to the query string.

Retrieving Docs as a Zip

Documents can also be retrieved as a zip file. In this instance, pass a list of the unique codes for the document to the service endpoint, it will retrieve and zip them before sending back to the caller.

{
    "documentCodes": ["doc1", "doc2", "doc3"]
}

For the get method documentCodes can be set as a query param. The param must be url encoded version of a comma delimited string of document client codes such as:

https://<US: api-us.kurtosys.app OR UK: api-uk.kurtosys.app>/documents/retrieveDocumentZip?documentCodes=doc1%2Cdoc2%2Cdoc3

An optional filename can also be specified to allow the file name saved for the zip archive to be overwritten when downloaded:

https://<US: api-us.kurtosys.app OR UK: api-uk.kurtosys.app>/documents/retrieveDocumentZip?documentCodes=doc1%2Cdoc2%2Cdoc3&filename=test.zip

Requested headers + URI should not be more than 80kb. Individual browsers may have their own URI length limits that should be respected.

Retrieving Docs By Tags

Documents can also be retrieved using tag values. This allows documents to be tagged with things like a legacy URL and be retrieved accordingly without setting up explicit redirects. Supports the provision of one meta property name and then multiple values. If more than one document matches, a zip will be returned.

{
    "property": "redirect_url",
    "values": ["https://www.kurtosys.com/docs/uploads/FACTSHEET-KS1319692791-de-DE.pdf"]
}

Retrieving Docs By File Name or Meta Type

Documents can be retrieved using a file name or meta data code. If there are multiple documents that match then a zip file will be returned containing the documents.

Examples

File name examples

• https:///documents/retrieve/755ef3fc-3632-4996-ba9f-e0f0a4de03c7/filename/LU1232123KIIDEN.pdf
• https:///documents/retrieve/755ef3fc-3632-4996-ba9f-e0f0a4de03c7/filename/LU1232123%20Factsheet%20DE.pdf

Metacode examples

• https:///documents/retrieve/755ef3fc-3632-4996-ba9f-e0f0a4de03c7/isin/KS0273642768
• https:///documents/retrieve/755ef3fc-3632-4996-ba9f-e0f0a4de03c7/bloomberg_code/MPCGLCA%20LX

No matching documents

If there are no matching documents a response code of 400 will be returned.

Example response body

{
    "error": "No documents found."
}

Searching For Documents by Fund, Share Class, Account or Benchmark Properties

It is possible to search for documents by their related fund or share class properties. This is useful as it allows you to search on a tag that is not directly applied to the document, but may be applied to the fund or share class it relates to.

In order to enable this feature it must be configured in the system in the client configuration section. To do this via the API you can invoke the following endpoint.

Sample configuration

{
    "code": "document_to_entity_search_conf",
    "config": {
        "document_to_entity_search_configuration": [
            {
                "type": "CLSS",
                "property": "is_primary",
                "joinSpecs": [
                    {
                        "propertyToJoinFrom": "fund_code",
                        "metaToJoinTo": {
                            "value": "fund_code"
                        }
                    },
                    {
                        "propertyToJoinFrom": "isin",
                        "metaToJoinTo": {
                            "value": "isin"
                        }
                    },
                    {
                        "propertyToJoinFrom": "umbrella",
                        "metaToJoinTo": {
                            "value": "umbrella"
                        }
                    }
                ]
            }
        ]
    }
}

You can create numerous rules in the document_to_entity_search_configuration array. Each rule tells the system about a field you want to be able to use for searching against documents, that exists on the fund or share class entity. For each, specify a type, either CLSS, FUND or ACCT, and a property, which must be a pre-existing fund or share class property code, then search on the specified property.

In the following joinSpecs area, specify which properties are used to find documents. The reason for this is that there may be a property of a share class that you want to search by. For example, the is_primary field which indicates if a share class is the primary share class of a fund. However, the documents themselves do not necessarily have a related is_primary field. However, they do have tags such as isin or fund_code or umbrella. The joinSpecs therefore tell the system which fields to use to find the documents.

In the example above, the system would find share classes by the is_primary field, harvest their fund_code, isin, and umbrella values, and then find any documents that have either of those values on them, in an "or" fashion.

Use the metaToJoinTo key where fields on the fund and class don't necessarily have the same name. You can use an "inferred" meta field as the target of the join. You can use the key "isInferred": true in the metaToJoinTo to do this.

The above options are for an entity linked search. The search is done through the document search service.

{
    "type": "CLSS",
    "search": [],
    "entitySearch": [
        {
            "property": "is_primary",
            "values": ["true"],
            "entityType": "CLSS"
        }
    ]
}

In the above example, the search is on the is_primary field, for all classes where that value is true. If there is a rule set up for the is_primary field, the system will execute the search as described above.

There are some features and restrictions with the feature:

• You can search across multiple linked entity properties.
• You can set up up rules that target both funds and share classes.
• You must set up rules for each property you use.

Searching For Documents using an Identifier Search

The identifier search can be used to implement a 'full text search' on document meta and entity properties. You pass an array of approved meta or 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.

When targeting entity properties, it will use the same client configuration logic as the Entity Search logic above. You will need to have a configuration defined for each property that you are attempting to use related to the entity.

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["isin"],
            "value": "345"
        }
    ]
}

This will target all documents with a meta property of isin which contains the value of "345". Adding fuzzy:true will make the search match any token in the string you provide. You can also target some of the document fields outside of the meta object.

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["title"],
            "value": "345",
            "meta": false
        }
    ]
}

Only "filename", "cultureCode" or "title" are allowed in the properties field when doing this, other properties will be ignored. Note that meta must explicitly be set to false here. The meta field will default to true if not provided.

To be able to search by inferred meta values, you can set the inferred flag to true. Like so:

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["type"],
            "value": "Performance",
            "inferred": true
        }
    ]
}

This will search through the inferred values associated to the document meta setup. It will traverse the inferred values and find a matching value and then apply the original meta field and value into the underlying search logic. Translations will be taken into account if they are provided in the search request body. An example of this would be:

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["type"],
            "value": "Leistung", // Performance in German
            "inferred": true
        }
    ],
    "translate": true,
    "sourceCulture": "en-GB",
    "culture": "de-DE"
}

You can also apply the identifier search to entities:

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "entity",
            "properties": ["isin"],
            "value": "345",
            "entityType": "CLSS"
        }
    ]
}

This will find all related documents associated to an entity of type CLSS, which has an isin that contains "345".

Identifier Search Operator

If you need to combine identifier searches, for example checking a single search value against both document and entity properties, you can set an identifierSearchOperator of AND or OR to specify how the searches should be combined. In the example below, the value provided would match to the short_name on the entity, and results would be provided.

The operator defaults to AND, which means that by default all identifier search clauses must match for results to be returned.

{
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["document_type"],
            "value": "CLASS R CHF HDG"
        },
        {
            "target": "entity",
            "entityType": "CLSS",
            "properties": ["short_name"],
            "value": "CLASS R CHF HDG"
        }
    ],
    "identifierSearchOperator": "OR"
}

Searching for documents using translations

The translations options can be used to translate the identifier search values passed in an identifier search. This logic will be applied if the translate flag is set to true, and will translate the search value from the culture into the sourceCulture and then perform the search based on the translated value.

In the current implementation, the translate logic does not translate the returned values. At present, this woud be handled client side.

{
    "type": "CLSS",
    "search": [],
    "identifierSearches": [
        {
            "target": "document",
            "properties": ["document_type"],
            "value": "Fiche descriptive" // "Factsheet" in French
        }
    ],
    "translate": true,
    "sourceCulture": "en-GB",
    "culture": "fr-FR"
}

Filtering Responses with specific fields

Property name: returnFields

Returns selected fields from the response. Based on npm package https://github.com/nemtsov/json-mask

The syntax is loosely based on XPath:

• a,b,c comma-separated list will select multiple fields
• a/b/c path will select a field from its parent
• a(b,c) sub-selection will select many fields from a parent
• a/_/c the star _ wildcard will select all items in a field

Examples

1.

A request without returnFields property

{
    "type": "FUND",
    "search": [
        {
            "property": "isin",
            "values": ["KS0453474941"],
            "matchtype": "MATCH"
        }
    ],
    "limit": 3
}

Response

{
    "total": 8,
    "values": [
        {
            "documentId": 141,
            "clientId": 2,
            "clientCode": "KIID-KS0453474941-en-GB",
            "title": "Kurtosys Alpha Fund A GBP Acc KIID",
            "fileType": "application/pdf",
            "cultureCode": "en-GB",
            "URL": "3554ccdc-6038-41ee-bbc6-809934497c05/docstorage/2216e933-942c-459e-8cfa-8e8a55ccc67d",
            "storagePath": "3554ccdc-6038-41ee-bbc6-809934497c05/docstorage/2216e933-942c-459e-8cfa-8e8a55ccc67d",
            "thumbNailPath": null,
            "meta": {
                "document_date": {
                    "value": "2017-09-15T08:48:18.643Z"
                },
                "document_type": {
                    "value": "KIID"
                },
                "isin": {
                    "value": "KS0453474941"
                }
            },
            "lastModified": "2023-09-28T13:42:29.000Z",
            "lastModifiedBy": 3,
            "created": "2023-09-28T13:42:29.000Z",
            "createdBy": 3,
            "fileSize": 47234,
            "active": 1,
            "expires": "0000-00-00 00:00:00",
            "docHash": "e71833870d4578ee6c14b759ab271e94000d9737",
            "filename": "KIID-KS0453474941-en-GB.pdf",
            "clientHosted": 0,
            "rowHash": "32731b8547481d80312abde2aefc91a49f6bffe414250f0a71d4c38cd973213d",
            "inferred": {}
        }
    ],
    "limit": 3
}

2.

The returnFields property can be used to filter response fields as follows:

Request

{
    "type": "FUND",
    "search": [
        {
            "property": "isin",
            "values": ["KS0453474941"],
            "matchtype": "MATCH"
        }
    ],
    "limit": 3,
    "returnFields": "clientCode,filename"
}

Response

{
    "total": 8,
    "values": [
        {
            "clientCode": "KIID-KS0453474941-en-GB",
            "filename": "KIID-KS0453474941-en-GB.pdf"
        }
    ],
    "limit": 3
}

Request

{
    "type": "FUND",
    "search": [
        {
            "property": "isin",
            "values": ["KS0453474941"],
            "matchtype": "MATCH"
        }
    ],
    "limit": 3,
    "returnFields": "meta(document_date,isin)"
}

Response

{
    "total": 8,
    "values": [
        {
            "meta": {
                "document_date": {
                    "value": "2017-09-15T08:48:18.643Z"
                },
                "isin": {
                    "value": "KS0453474941"
                }
            }
        }
    ],
    "limit": 3
}

Retrieve possible filters

This allows you to list all possible property value options for document meta and/or inferred meta data properties. In the example below, all the possible property/tag values for documents with the tags of document_type, ccy, frequency, invalid_code are queried, it will also further filter if supplied with a search clause. If document entitlements are enabled, results are filtered based on entitlement configuration also.

Note that in this example we have setup frequency as inferred meta which returns monthly where document_type is 'Factsheet' and annually where document_type is 'KIID'.

{
    "codes": ["document_type", "ccy", "frequency", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ]
}

The above query scans all documents and returns a listing of the various meta values for the document_type, ccy, frequency and invalid_code property.

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

{
    "ccy": [
        {
            "label": "na",
            "value": "GBP"
        },
        {
            "label": "na",
            "value": ["ZAR", "USD"]
        }
    ],
    "document_type": [
        {
            "label": "na",
            "value": "Factsheet"
        },
        {
            "label": "na",
            "value": "KIID"
        }
    ],
    "frequency": [
        {
            "label": "na",
            "value": "monthly"
        },
        {
            "label": "na",
            "value": "annually"
        }
    ],
    "invalid_code": []
}

Retrieve Filters Search Property

By passing the search property in the payload,

{
    "codes": ["document_type", "ccy", "frequency", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["Factsheet"],
            "matchtype": "MATCH"
        }
    ]
}

you can filter down the codes even more:

{
    "ccy": [
        {
            "label": "na",
            "value": "GBP"
        },
        {
            "label": "na",
            "value": ["ZAR", "USD"]
        }
    ],
    "document_type": [
        {
            "label": "na",
            "value": "Factsheet"
        }
    ],
    "frequency": [
        {
            "label": "na",
            "value": "monthly"
        }
    ],
    "invalid_code": []
}

You can also pass inferred meta as part of the search property

{
    "codes": ["document_type", "ccy", "frequency", "invalid_code"],
    "search": [
        {
            "property": "frequency",
            "values": ["annually"],
            "matchtype": "MATCH"
        }
    ]
}

Which would further filter the results as before:

{
    "ccy": [
        {
            "label": "na",
            "value": "GBP"
        },
        {
            "label": "na",
            "value": ["ZAR", "USD"]
        }
    ],
    "document_type": [
        {
            "label": "na",
            "value": "KIID"
        }
    ],
    "frequency": [
        {
            "label": "na",
            "value": "annually"
        }
    ],
    "invalid_code": []
}

Retrieve Filters SpreadArray Property

By passing the spreadArrays property in the payload as true,

{
    "codes": ["document_type", "ccy", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ],
    "spreadArrays": true
}

the values that would have been arrays will be spread:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP"
        },
        {
            "label": "ZAR",
            "value": "ZAR"
        },
        {
            "label": "USD",
            "value": "USD"
        }
    ],
    "document_type": [
        {
            "label": "Factsheet",
            "value": "Factsheet"
        },
        {
            "label": "KIID",
            "value": "KIID"
        }
    ],
    "invalid_code": []
}

Retrieve Filters uniqueOptionsOnly Property

By passing the uniqueOptionsOnly property in the payload as true,

{
    "codes": ["document_type", "ccy", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ],
    "spreadArrays": true,
    "uniqueOptionsOnly": true
}

the values that would have been arrays will be spread and duplicates removed, in this case ccy contained ["GBP","ZAR","USD"] and ["GBP"] for seperate documents:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP"
        },
        {
            "label": "ZAR",
            "value": "ZAR"
        },
        {
            "label": "USD",
            "value": "USD"
        }
    ],
    "document_type": [
        {
            "label": "Factsheet",
            "value": "Factsheet"
        },
        {
            "label": "KIID",
            "value": "KIID"
        }
    ],
    "invalid_code": []
}

Retrieve Filters uniqueOptionsOnly & counts Property

By passing the uniqueOptionsOnly property & counts in the payload as true,

{
    "codes": ["document_type", "ccy", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ],
    "spreadArrays": true,
    "uniqueOptionsOnly": true,
    "counts": true
}

the values that would have been arrays will be spread and duplicates removed, in this case ccy contained ["GBP","ZAR","USD"] and ["GBP"] for seperate documents:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP",
            "count": 2
        },
        {
            "label": "ZAR",
            "value": "ZAR",
            "count": 1
        },
        {
            "label": "USD",
            "value": "USD",
            "count": 1
        }
    ],
    "document_type": [
        {
            "label": "Factsheet",
            "value": "Factsheet",
            "count": 1
        },
        {
            "label": "KIID",
            "value": "KIID",
            "count": 1
        }
    ],
    "invalid_code": []
}

Retrieve Filters using Identifier Searches

By passing the identifierSearches property in the payload,

{
    "codes": ["isin", "document_date"],
    "identifierSearches": [
        {
            "target": "entity",
            "properties": ["isin"],
            "value": "KS13196927912",
            "entityType": "CLSS"
        }
    ]
}

{
    "isin": [{ "value": "KS13196927912", "label": "KS13196927912" }],
    "document_date": [
        {
            "value": "2017-09-08T11:58:28.188Z",
            "label": "2017-09-08T11:58:28.188Z"
        },
        {
            "value": "2017-09-08T11:58:29.946Z",
            "label": "2017-09-08T11:58:29.946Z"
        },
        {
            "value": "2017-09-08T11:58:31.569Z",
            "label": "2017-09-08T11:58:31.569Z"
        }
    ]
}

Retrieve Filters with Entity Searches

You can create numerous rules in the document_to_entity_search_configuration array. Each rule tells the system about a field you want to be able to use for retrieving document filters, that exists on the entity types. For each, specify a type, either CLSS, FUND, ACCT or BMRK, and a property, which must be a pre-existing entity property code, then search on the specified property.

In the example above, the system would find share classes by the isin field, harvest their isin, document_date, fund_code, umbrella and document_type values, and then link any documents that have either of those values on them, in an "or" fashion.

By passing the entitySearch property in the payload

{
    "codes": ["isin", "document_date", "fund_code", "umbrella", "document_type"],
    "entitySearch": [
        {
            "property": "isin",
            "values": ["KS1319692791"],
            "entityType": "CLSS"
        }
    ]
}

{
    "isin": [{ "value": "KS1319692791", "label": "KS1319692791" }],
    "document_date": [
        {
            "value": "2017-09-08T11:58:28.188Z",
            "label": "2017-09-08T11:58:28.188Z"
        },
        {
            "value": "2017-09-08T11:58:29.946Z",
            "label": "2017-09-08T11:58:29.946Z"
        },
        {
            "value": "2017-09-08T11:58:31.569Z",
            "label": "2017-09-08T11:58:31.569Z"
        }
    ],
    "fund_code": [
        { "value": "ALPHA", "label": "ALPHA" },
        { "value": "BONDY", "label": "BONDY" }
    ],
    "umbrella": [{ "value": "Alternative", "label": "Alternative" }],
    "document_type": [
        { "value": "Annual Report", "label": "Annual Report" },
        { "value": "Factsheet", "label": "Factsheet" },
        { "value": "Overview", "label": "Overview" }
    ]
}

Retrieve filters with search entity request

A search entity request can be used to find the filter values based on entity search results. Adding this field will fire a searchEntity request and return a list of entities which will then be matched against documents. All options available for the searchEntity request are given here, allowing the use of segmentation lists etc. to filter the document filter results.

{
    "codes": ["isin", "document_date", "fund_code", "umbrella", "document_type"],
    "searchEntityRequest": {
        "type": "CLSS",
        "fundList": "intermediaries_LU",
        "fundListExclusion": ["exclude_a_segment"],
        "search": [
            {
                "property": "share_class",
                "values": ["EB"],
                "matchtype": "MATCH"
            }
        ]
    }
}

Retrieve Filters Translation Property

By passing the translation properties in the payload,

{
    "codes": ["document_type", "ccy", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ],
    "translation": {
        "sourceCulture": "en-GB",
        "culture": "fr-FR"
    }
}

the labels will be translated where applicable:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP"
        },
        {
            "label": "ZAR",
            "value": "ZAR"
        },
        {
            "label": "USD",
            "value": "USD"
        }
    ],
    "document_type": [
        {
            "label": "Fiche descriptive",
            "value": "Factsheet"
        },
        {
            "label": "KIID",
            "value": "KIID"
        }
    ],
    "invalid_code": []
}

Retrieve Entity Filters

This allows you to list all possible property value options for entities that are linked to the documents returned via a document search.

In the example below, all the possible property values for linked entities with the tags of fund_code, umbrella are queried. It will also filter lnked documents if supplied with a search clause. If document entitlements are enabled, linked document results are filtered based on entitlement configuration also.

{
    "codes": ["fund_code", "umbrella", "invalid_code"],
    "joinSpecs": [
        {
            "entityType": "CLSS",
            "joinFrom": "isin",
            "joinTo": "isin"
        }
    ],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ]
}

The above query scans all entities that are linked to documents via the isin field, and returns a listing of the various properties_pub values for the fund_code andumbrella property. The joinSpecs must be specified to link entities to documents in order to access results.

If a property is not a valid entity property, it will be returned with an empty array.

{
    "fund_code": [
        {
            "label": "ALPHA",
            "value": "ALPHA"
        },
        {
            "label": "BOND",
            "value": ["BOND", "BOND"]
        }
    ],
    "umbrella": [
        {
            "label": "Alternative",
            "value": "Alternative"
        },
        {
            "label": "Fixed Income",
            "value": "Fixed Income"
        }
    ],
    "invalid_code": []
}

Retrieve Entity Filters Search Property

By passing the search property in the payload, you can limit the linked documents that are used to match with entities.

Retrieve Entity Filters SpreadArray Property

By passing the spreadArrays property in the payload as true,

{
    "codes": ["ccy", "invalid_code"],
    "joinSpecs": [
        {
            "entityType": "CLSS",
            "joinFrom": "isin",
            "joinTo": "isin"
        }
    ],
    "spreadArrays": true
}

the values that would have been arrays will be spread:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP"
        },
        {
            "label": "ZAR",
            "value": "ZAR"
        },
        {
            "label": "USD",
            "value": "USD"
        }
    ],
    "invalid_code": []
}

Retrieve Entity Filters uniqueOptionsOnly Property

By passing the uniqueOptionsOnly property in the payload as true,

{
    "codes": ["ccy", "invalid_code"],
    "joinSpecs": [
        {
            "entityType": "CLSS",
            "joinFrom": "isin",
            "joinTo": "isin"
        }
    ],
    "spreadArrays": true,
    "uniqueOptionsOnly": true
}

the values that would have been arrays will be spread and duplicates removed, in this case ccy contained ["GBP","ZAR","USD"] and ["GBP"] for separate entities:

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP"
        },
        {
            "label": "ZAR",
            "value": "ZAR"
        },
        {
            "label": "USD",
            "value": "USD"
        }
    ],
    "invalid_code": []
}

Retrieve Entity Filters uniqueOptionsOnly & counts Property

By passing the uniqueOptionsOnly property & counts in the payload as true,

{
    "codes": ["ccy", "invalid_code"],
    "joinSpecs": [
        {
            "entityType": "CLSS",
            "joinFrom": "isin",
            "joinTo": "isin"
        }
    ],
    "spreadArrays": true,
    "uniqueOptionsOnly": true,
    "counts": true
}

the values that would have been arrays will be spread and duplicates removed, in this case ccy contained ["GBP","ZAR","USD"] and ["GBP"] for separate entities. The count values indicate how many linked documents there are for each of the entity values returned.

{
    "ccy": [
        {
            "label": "GBP",
            "value": "GBP",
            "count": 2
        },
        {
            "label": "ZAR",
            "value": "ZAR",
            "count": 1
        },
        {
            "label": "USD",
            "value": "USD",
            "count": 1
        }
    ],
    "invalid_code": []
}

Retrieve Entity Filters using Identifier Searches and/or Entity Search

By passing the identifierSearches or entitySearch property in the payload, we can limit the number of linked documents found. See the getFilters section above for further details on how the entity search is applied.

{
    "codes": ["isin", "fund_code"],
    "identifierSearches": [
        {
            "target": "entity",
            "properties": ["isin"],
            "value": "KS13196927912",
            "entityType": "CLSS"
        }
    ],
    "entitySearch": [
        {
            "property": "isin",
            "values": ["KS13196927912"],
            "entityType": "CLSS"
        }
    ]
}

Retrieve entity filters with search entity request

A search entity request can be used to find the filter values based on entity search results. Adding this field will fire a searchEntity request and return a list of entities which will then be matched against documents. All options available for the searchEntity request are given here, allowing the use of segmentation lists etc. to filter the entity filter results.

{
    "codes": ["isin", "document_date", "fund_code", "umbrella", "document_type"],
    "searchEntityRequest": {
        "type": "CLSS",
        "fundList": "intermediaries_LU",
        "fundListExclusion": ["exclude_a_segment"],
        "search": [
            {
                "property": "share_class",
                "values": ["EB"],
                "matchtype": "MATCH"
            }
        ]
    }
}

Retrieve Entity Filters Translation Property

By passing the translation properties in the payload,

{
    "codes": ["region", "invalid_code"],
    "search": [
        {
            "property": "document_type",
            "values": ["KIID", "Factsheet"],
            "matchtype": "MATCH"
        }
    ],
    "translation": {
        "sourceCulture": "en-GB",
        "culture": "fr-FR"
    }
}

the labels will be translated where applicable:

{
    "region": [
        {
            "label": "United Kingdom",
            "value": "UK"
        },
        {
            "label": "United States",
            "value": "US"
        }
    ],
    "invalid_code": []
}

Document Facets

It is possible to return facets based on a search term. The supported facet types are: document meta, document filename and entity properties, as defined by the document to entity search configuration. Results are grouped by property and limited to 10 results per propertyValues.

An additional translation value may be added to the request if the endpoint is being called by an app using translations. The sourceCulture and culture must be specified, and the culture will be used to match the search term to a value in the source culture. The property and propertyValue in the response will be returned in the culture specified, and the originalProperty and originalPropertyValue wll be returned in the source culture. Only values that have the field include in translations checked inside of the Data Dictionary will be returned for document meta

The documentSearch value can be included in the request to restrict the facet results to documents that match the document search. An example of where this might be used is in a document explorer, where the document search would include filter values and the getFacets endpoint would restrict the results available in a faceted search.

{
    "searchTerm": "fact",
    "translation": {
        "sourceCulture": "en-GB",
        "culture": "it-IT"
    },
    "documentSearch": {
        "type": "CLSS",
        "search": [
            {
                "property": "active",
                "matchtype": "MATCH",
                "values": ["true"]
            }
        ]
    }
}

Example response

[
    {
        "originalProperty": "Document Type",
        "property": "Document Type (Italian)",
        "propertyValues": [
            {
                "originalPropertyValue": "Factsheet",
                "propertyValue": "Factsheet (Italian)",
                "originalProperty": "Document Type",
                "property": "Document Type (Italian)",
                "code": "document_type",
                "facetType": "META"
            }
        ]
    },
    {
        "originalProperty": "File Name",
        "property": "File Name (Italian)",
        "propertyValues": [
            {
                "originalPropertyValue": "FACTSHEET.pdf",
                "propertyValue": "FACTSHEET_ITALIAN.pdf",
                "originalProperty": "File Name",
                "property": "File Name (Italian)",
                "code": "filename",
                "facetType": "DOCUMENT_PROPERTY"
            }
        ]
    }
]

Document Entitlements

A user with the system role "DocumentAdmin" will bypass all entitlement filters and be able to list, retrieve or update all documents on the respective client.

User Document Entitlement Schemes

This will set the provided user's document entitlement scheme to the one schemeId provided. Either the userId or externalUserIdentifier can be used to identify the user to update.

{
    "userId": 20,
    "documentEntitlementSchemeId": 1
}

Or

{
    "externalUserIdentifier": "K99282ss92",
    "documentEntitlementSchemeId": 1
}

Upsert User Document Entitlement

{
    "userId": 20,
    "documentEntitlementSchemeId": 1,
    "documentEntitlements": [
        {
            "tag": "document_type",
            "value": "factsheet",
            "endDate": "2017-12-15"
        },
        {
            "tag": "document_type",
            "value": "image",
            "startDate": "2017-11-11",
            "endDate": "2017-12-15"
        },
        {
            "tag": "isin",
            "value": "f1232",
            "startDate": "2017-11-11",
            "endDate": "2017-12-14"
        }
    ]
}

List User Document Entitlements

{
    "userId": 20
}

Delete User Document Entitlements

{
    "userId": 20,
    "documentEntitlements": [
        {
            "tag": "document type",
            "value": "isin"
        },
        {
            "tag": "document type",
            "value": "isin",
            "startDate": "2017-11-11"
        },
        {
            "tag": "document type",
            "value": "other",
            "startDate": "2017-11-11"
        }
    ]
}

Bulk Change of User Document Entitlement Schemes

Bulk Add Entitlements

This endpoint adds document entitlements to multiple users.

A user can only have one Entitlement Scheme at a time. If any users are already assigned to an entitlement scheme that is different to the one in the request then the process exits early and returns the invalid users.

{
    "userNames": ["usernameOne", "usernameTwo", "usernameThree"],
    "documentEntitlementSchemeName": "Marketing Entitlements",
    "documentEntitlements": [
        {
            "tag": "document_type",
            "value": "factsheet",
            "endDate": "2017-12-15"
        },
        {
            "tag": "document_type",
            "value": "image",
            "startDate": "2017-11-11",
            "endDate": "2017-12-15"
        },
        {
            "tag": "isin",
            "value": "f1232",
            "startDate": "2017-11-11",
            "endDate": "2017-12-14"
        }
    ]
}

This can also be called with externalUserIdentifiers instead of the userNames array:

{
    "externalUserIdentifiers": ["identifierOne", "identifierTwo", "identifierThree"]
}

Where users are already assigned to an Entitlement Scheme and their userNames are sent in the request, the response is as follows:

{
    "invalidUsers": [105, 107, 119],
    "userNames": ["usernameFive", "usernameSever", "usernameOneOneNine"],
    "externalUserIdentifiers": []
}

Where users are already assigned to an Entitlement Scheme and their externalUserIdentifiers are sent in the request, the response is as follows:

{
    "invalidUsers": [105, 107, 119],
    "userNames": [],
    "externalUserIdentifiers": ["exterIdXX8", "exterIdYZ93", "exterIdAbb52"]
}

Bulk Replace Entitlements

{
    "userNames": ["usernameOne", "usernameTwo", "usernameThree"],
    "documentEntitlementSchemeName": "Marketing Entitlements",
    "documentEntitlements": [
        {
            "tag": "document_type",
            "value": "factsheet",
            "endDate": "2017-12-15"
        },
        {
            "tag": "document_type",
            "value": "image",
            "startDate": "2017-11-11",
            "endDate": "2017-12-15"
        },
        {
            "tag": "isin",
            "value": "f1232",
            "startDate": "2017-11-11",
            "endDate": "2017-12-14"
        }
    ]
}

This can also be called with externalUserIdentifiers instead of the userNames array:

{
    "externalUserIdentifiers": ["identifierOne", "identifierTwo", "identifierThree"]
}

Document Entitlement Schemes

Upsert

To upsert a document entitlement scheme, use the following endpoint. The name is unique per client, using the same name will result in updating the scheme instead of creating a new one.

{
    "name": "abc",
    "tags": ["blue", "green", "red"]
}

Or, for updating:

{
    "documentEntitlementSchemeId": 123,
    "name": "New ABC",
    "tags": ["blue", "green"]
}

List

Get a list of the document entitlement schemes.

Delete

To delete a document entitlement scheme, use the following endpoint.

{
    "documentEntitlementSchemeId": 20
}

Saved Searches

Once you have performed a search, you have the ability to save this search for future use. Give the search a name, you can activate search notifications. If you opt for notifications, these can be sent out on a Daily or Weekly occurrence.

List Saved Searches

{
    "savedSearchName": "KIID"
}

Example response

{
    "total": 2,
    "values": [
        {
            "savedSearchId": 1,
            "savedSearchName": "TBC KIIDs",
            "notificationFrequency": "Daily",
            "created": "2017-09-08T00:00:00.000Z",
            "lastModified": "2017-12-08T10:37:56.123Z",
            "search": {
                "type": "CLSS",
                "search": [
                    {
                        "matchtype": "MATCH",
                        "property": "document_type",
                        "values": ["KIID"]
                    },
                    {
                        "matchtype": "MATCH",
                        "property": "isin",
                        "values": ["TBC"]
                    }
                ],
                "sort": {
                    "key": "isin",
                    "direction": "DESC"
                }
            }
        },
        {
            "savedSearchId": 2,
            "savedSearchName": "RW KIIDs",
            "created": "2017-10-08T00:00:00.000Z",
            "lastModified": "2017-12-08T10:37:56.123Z",
            "search": {
                "type": "CLSS",
                "search": [
                    {
                        "matchtype": "MATCH",
                        "property": "document_type",
                        "values": ["KIID"]
                    }
                ],
                "filters": [
                    {
                        "matchtype": "MATCH",
                        "property": "isin",
                        "values": ["RWCEFF000001"]
                    }
                ],
                "sort": {
                    "key": "isin",
                    "direction": "DESC"
                }
            }
        }
    ]
}

The response does not return a limit as this returns all values.

The search clause allows an optional filters value to be specified. These values are the same shape as the search values and can be handled separately in the UI where filters are used.

Upsert Saved Search

Creation Call

For creation, no savedSearchId is passed. The X-KSYS-APP is used to determine the application that the saved search belongs to.

{
    "savedSearchName": "RW KIIDs",
    "notificationFrequency": "weekly",
    "search": {
        "type": "CLSS",
        "search": [
            {
                "matchtype": "MATCH",
                "property": "document_type",
                "values": ["KIID"]
            }
        ],
        "sort": {
            "key": "filename",
            "direction": "ASC"
        },
        "filenames": ["KIID-KS0273642768-de-DE.pdf"]
    }
}

Example response

{
    "savedSearchName": "RW KIIDs",
    "notificationFrequency": "weekly",
    "search": {
        "type": "CLSS",
        "search": [
            {
                "matchtype": "MATCH",
                "property": "document_type",
                "values": ["KIID"]
            }
        ],
        "sort": {
            "key": "filename",
            "direction": "ASC"
        },
        "filenames": ["KIID-KS0273642768-de-DE.pdf"]
    }
}

Update Call

For update, the savedSearchId is passed as well as anything that should change.

{
    "savedSearchId": 1,
    "savedSearchName": "RW KIIDs renamed",
    "notificationFrequency": "daily"
}

Example response

{
    "savedSearchId": 1,
    "savedSearchName": "RW KIIDs renamed",
    "notificationFrequency": "daily",
    "search": {
        "type": "CLSS",
        "search": [
            {
                "matchtype": "MATCH",
                "property": "document_type",
                "values": ["KIID"]
            }
        ],
        "sort": {
            "key": "filename",
            "direction": "ASC"
        },
        "filenames": ["KIID-KS0273642768-de-DE.pdf"]
    }
}

Delete Saved Search

Only the creator of the saved search can delete it. Returns a 204.

{
    "savedSearchId": "1234"
}

Document Filename Check

Checks if a list of document filenames exist for a client.

{
    "documentFilenames": ["KS123456780.pdf", "KS123456781.pdf", "KS123456782.pdf", "KS123456783.pdf"]
}

Will return an empty list if the documents do not exist, and a list containing duplicates if they match an existing document.

No Existing Documents

Status: 200

{
    "existingDocuments": []
}

Existing Documents

Status: 200

{
    "existingDocuments": ["KS123456780.pdf"]
}

Friendly Document URLs

This endpoint will return a list of friendly document urls for the provided document. It will return all possible combinations, based on the current Custom Document URLs setup within the KurtosysApp.

If there is no Custom Document URL setup, it will return an empty array.

{
    "clientCode": "asdfasdf"
}

No Friendly Document URLs

Status: 200

{
    "urls": []
}

Friendly Document URLs

Status: 200

{
    "urls": [
        "https://www.clientdomain.com/documents/annual-fees/en/ie/institutional/KIID-KS1234.pdf",
        "https://www.clientdomain.com/documents/annual-fees/de/de/intermediary/KIID-KS1234.pdf"
    ]
}

Document Retrieval Statistics

The endpoint will retrieve and return document retrieval statistics data for the startDate and endDate date range provided. The date fields are optional and if not supplied the api will default to the last month. If only the startDate is provided it will default the end date to today.

The period is used to calculate the start or end of a unit of time, e.g. start of 'year' will translate to January 1st, 12:00 am of this year. Supported values are YEAR, MONTH, DAY, HOUR, MINUTE, SECOND with the default being DAY if none is specified. This will override the date range if it is set to a unit larger than the range provided.

It will also return the values for the document meta(s) specified by the documentMeta property in the payload. This is optional and will be excluded from the results if not provided.

The results will be ordered by dateTimeAccessed DESC.

{
    "startDate": "2022-03-01",
    "endDate": "2022-03-07",
    "period": "DAY",
    "documentMeta": ["document_date", "document_type", "isin"]
}

Example response

[
    {
        "document_date": "2019-04-28T11:31:45.900Z",
        "document_type": "Factsheet",
        "isin": "KS0883643401",
        "title": "Document Download Breakdown",
        "accessedUsername": "user1",
        "origin": "api-local.fundpress.io",
        "referer": "https://app-local.kurtosys.app/documents/document-management",
        "dateTimeAccessed": "2022-03-03T12:09:12.000Z"
    },
    {
        "document_date": "2020-09-01T08:57:13.900Z",
        "document_type": "KIID",
        "isin": "KS0323643653",
        "title": "Kurtosys Bond B USD Acc Factsheet",
        "accessedUsername": "user2",
        "origin": "api-local.fundpress.io",
        "referer": "https://app-local.kurtosys.app/documents/document-management",
        "dateTimeAccessed": "2022-03-02T07:18:08.000Z"
    }
]