Virtual Tag Metadata API

The Finout Metadata API allows you to query, analyze, and manage metadata associated with virtual tag values. It provides functionalities to retrieve existing metadata lists and add metadata for specific virtual tags. Results are returned in JSON format, facilitating seamless data processing and integration.

GET/Virtual Tag Metadata

Returns a list of virtual tag values and their corresponding Metadata

Prerequisites

• You must obtain the Virtual Tag ID by querying GET/virtual-tags.

• Generate a Client ID and Secret Key from Finout to add in Headers.

Request

https://app.finout.io/v1/virtual-tags/virtualtagid/metadata

Response

200

{
    "requestId": "ff8bef06-a211-49aa-b169-cbc8e240b1d7",
    "metadata": {
        "App Team": {
            "groups": [
                "d704e672-b33c-4fda-b4fc-bde7a8774de4"
            ],
            "customMetadata": {
                "owner": "Dave"
            },
            "endpoints": [
                "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
            ]
        },
        "Data Team": {
            "groups": [
                "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
            ],
            "customMetadata": {
                "owner": "Dan"
            },
            "endpoints": [
                "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
            ]
        },
        "DevOps Team": {
            "groups": [
                "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
            ],
            "customMetadata": {
                "owner": "Sam"
            }
        }
    }
}

400

Bad Request

401

Unauthorized

429

Too many requests

503

Server unavailable

504

Gateway Timeout

Returns a JSON object with the following properties:

• Request Id - The unique identifier for the API request.

• Custom Metadata - Any metadata attached to the virtual tag.

PUT/Virtual Tag Metadata

Enrich your virtual tag values with groups and custom metadata by adding them to your virtual tag and specifying them per value. This metadata is also used with other objects in Finout.

Note:

• Currently, using virtual tag values metadata is only available in Financial Plans.

• Adding virtual tag metadata using the PUT query overrides the current data in the virtual tag.

• Documentation to learn more about utilizing metadata in financial plans is coming soon.

Prerequisites

• You must obtain the Virtual Tag ID by querying a GET/virtual-tags.
• Generate a Client ID and Secret Key from Finout to add in Headers.

Request

https://app.finout.io/v1/virtual-tags/virtualtagID/metadata Use Case: Assume your organization has three teams: App Team, Data Team, and DevOps Team. You need to configure groups for each team and assign an owner name for each team.

200

{
    "App Team": {
        "groups": [
            "d704e672-b33c-4fda-b4fc-bde7a8774de4"
        ],
        "customMetadata": {
            "owner": "Dave"
        },
        "endpoints": [
            "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
        ]
    },
    "Data Team": {
        "groups": [
            "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
        ],
        "customMetadata": {
            "owner": "Dan"
        },
        "endpoints": [
            "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
        ]
    },
    "DevOps Team": {
        "groups": [
            "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
        ],
        "customMetadata": {
            "owner": "Sam"
        }
    }
}

Body of Request

Parameter	Type	Description
Virtual Tag Value	String	The object that defines the value for the virtual tag. This can be of any value. ​Limitation: Virtual tag values in this specific endpoint cannot include dots. For more information, see Virtual Tags.
customMetadata	Object	Any type of metadata can be attached to the virtual tag’s value. You must specify the custom metadata key and value. Example: If you want to assign an owner to a virtual tag’s value, you can set "owner" as the custom metadata key and "owner_name" as the custom metadata value. For more information, see Financial Plans.
groups	Array	The group of this specific value. You can use one or more groups. To get account group IDs, contact your customer success representative. For more information, see Financial Plans.
endpoints	Array	An endpoint of this specific value. You can set one or more endpoints. ​Example: If the virtual tag’s value is "app team," you can provide the endpoint ID of the app team. ​{ "endpoint":"endpoint-app-team-id" } To learn how to get a list of your account's endpoints, see Endpoint API. See Reports to learn how to send reports to various endpoints.
mergeValuesAndMetadata	Boolean	Determines how Virtual Tag metadata is updated. If false (default), all existing metadata and values are overridden. If true, the payload is merged with existing data instead of replacing it.

Response

200

{
    "requestId": "68849e84-6fe5-4605-939a-72ccdec138b6",
    "metadata": {
        "App Team": {
            "groups": [
                "d704e672-b33c-4fda-b4fc-bde7a8774de4"
            ],
            "customMetadata": {
                "owner": "Dave"
            },
            "endpoints": [
                "770e4021-08f3-48d9-bdc1-ae9a8fd07cea"
            ]
        },
        "Data Team": {
            "groups": [
                "f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
            ],
            "customMetadata": {
                "owner": "Dan"
            },
            "endpoints": [
                "4f806937-6f5b-478e-a81a-f4b2ece14bb1"
            ]
        },
        "DevOps Team": {
            "groups": [
                "4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
            ],
            "customMetadata": {
                "owner": "Sam"
            }
        }
    },
    "request": {
        "virtualTagId": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89"
    }
}

Errors

400	Bad Request
401	Unauthorized
429	Too many requests
503	Server unavailable
504	Gateway Timeout

Returns a JSON object with the following properties:

• Request Id - The unique identifier for the API request.

• Custom Metadata - Any metadata attached to the virtual tag.