Overview

The Reference Data API is a collection of API operations for managing platform-wide reference data.

In the current implementation, the Reference Data API supports the creation and management of tags and tag groups. These resources enable organizations to work more efficiently by applying metadata labels to data sources.

Understanding tags

A tag is a keyword or label that can be assigned to risk data sources (e.g. an account, database, profile, or treaty) to facilitate searching and automation.

Tags can be organized and managed using tag groups. A tag group is a collection of tags. The tags within a tag group are organized by tag entity, a prefined structure for categorizing tags. The tenant may create an manage multiple tag groups to organize their tags in any way they find appropriate.

Creating tags and tag groups

Managing tags

Portfolio Managers and Cat Modelers may create, update, and delete tags using the Reference Data API.

Custom tags may be used to label data resources by type, year, region, customer, line of business, or any other attribute that makes sense for a business. For example, 2023, US Coast, or Monthly Report.

Best practices when creating tags:

• Establish a standard naming convention for tags within your organization.
• Check to see if an appropriate data tag already exists before before creating a new data tag. If you already have a "US" data tag, do not create a "USA" or "United States" data tag.
• Do not differentiate tags with capitalization. The names of tags are case-insensitive; the data tag us is identical to the data tag US.

Managing tag groups

Portfolio Managers and Cat Modelers can create, update, and delete tag groups using the Reference Data API.

Tag groups enable you to organize tags by team, year, region, customer, line of business, or any other rubric that makes sense for a business.

For example, the following tag group collects tags belonging to its Western office. The three tag entities collect tags that identify Databases (1), Profiles (3), and Treaties (6):

{
  "tagGroupName": "West",
  "tagGroupId": 5,
  "createdAt": "2024-07-08T20:11:41.288Z",
  "updatedAt": "2024-07-08T20:11:41.288Z",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "description": "Tags for western business organization",
  "entityMap": [
    {
      "entityId": 1,
      "tagIds": [11, 23, 33]
    },
    {
      "entityId": 3,
      "tagIds": [14, 15, 36]
    },
    {
      "entityId": 6,
      "tagIds": [45, 57, 63, 89]
    }
  ],
  "isPrivate": true
}

The entityMap is an array of mappings between a tag entity and a group of tags. A tag entity is a predefined bucket for organizing tags within a tag group. Platform API supports nine types of tag entities that that identified by tagEntityID:

Applying tags to data resources

Clients can apply tags (by tag ID) to appropriate data resources using various Platform API operations.

Filtering data resources by tag IDs

All roles can search data resources and define query strings to filter those resources based on the tags applied to them.

A filter consists of a single expression that defines an property, a condition (a property value), and an operator (e.g. = or LIKE). The filter keyword supports three filtering operations: comparison operations, logical operations, and list operations.

Platform APIs support filtering by tag ID in the following operations: