# 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.

## <mark style="color:green;">`GET`</mark>`/Virtual Tag Metadata`

Returns a list of virtual tag values and their corresponding Metadata

{% hint style="success" %}
**Prerequisites**

* You must obtain the Virtual Tag ID by querying [GET/virtual-tags](https://docs.finout.io/api/finout-api/virtual-tags-api).
* [Generate a Client ID and Secret Key ](https://docs.finout.io/api/finout-api/generate-an-api-token)from Finout to add in Headers.
  {% endhint %}

**Request**

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

**Response**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "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"
            }
        }
    }
}
</code></pre>

{% endtab %}

{% tab title="400" %}
Bad Request
{% endtab %}

{% tab title="401" %}
Unauthorized
{% endtab %}

{% tab title="429" %}
Too many requests
{% endtab %}

{% tab title="503" %}
Server unavailable
{% endtab %}

{% tab title="504" %}
Gateway Timeout
{% endtab %}
{% endtabs %}

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.

## <mark style="color:green;">`PUT`</mark>`/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.&#x20;

{% hint style="info" %}
**Note**:

* Currently, using virtual tag values metadata is only available in [Financial Plans](https://docs.finout.io/user-guide/inform/financial-plans#h_71f9175d15).
* Adding virtual tag metadata using the PUT query overrides the current data in the virtual tag.
  {% endhint %}

{% hint style="success" %}
**Prerequisites**

* You must obtain the Virtual Tag ID by querying a [GET/virtual-tags](https://docs.finout.io/api/finout-api/virtual-tags-api).
* [Generate a Client ID and Secret Key](https://docs.finout.io/api/finout-api/generate-an-api-token) from Finout to add in Headers.
  {% endhint %}

**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.

{% tabs %}
{% tab title="200" %}

```json
{
    "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"
        }
    }
}
```

{% endtab %}
{% endtabs %}

*Body of Request*

<table data-header-hidden><thead><tr><th width="272"></th><th></th><th></th></tr></thead><tbody><tr><td><h4 id="h_8a7794702b">Parameter</h4></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>Virtual Tag Value</td><td>String</td><td>The object that defines the value for the virtual tag. This can be of any value.<br>​Limitation:<br>Virtual tag values in this specific endpoint cannot include dots.<br>For more information, see <a href="../../user-guide/inform/virtual-tags">Virtual Tags</a>.</td></tr><tr><td>customMetadata</td><td>Object</td><td><p>Any type of metadata can be attached to the virtual tag’s value. You must specify the custom metadata key and value.</p><p>Example:</p><p>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.<br>For more information, see <a href="../../../user-guide/inform/financial-plans#h_71f9175d15">Financial Plans</a>.</p></td></tr><tr><td>groups</td><td>Array</td><td><p>The group of this specific value. You can use one or more groups.</p><p>To get account group IDs, contact your customer success representative.<br>For more information, see <a href="../../../user-guide/inform/financial-plans#h_55e4e09a6a">Financial Plans</a>.</p></td></tr><tr><td>endpoints</td><td>Array</td><td><p>An endpoint of this specific value. You can set one or more endpoints.<br>​Example:<br>If the virtual tag’s value is "app team," you can provide the endpoint ID of the app team.<br>​<code>{</code><br><code>"endpoint":"endpoint-app-team-id"</code><br><code>}</code></p><p><br>To learn how to get a list of your account's endpoints, see <a href="endpoint-api">Endpoint API</a>.<br><br>See <a href="../../user-guide/operate/reports">Reports</a> to learn how to send reports to various endpoints.</p></td></tr><tr><td>mergeValuesAndMetadata</td><td>Boolean</td><td>Determines how Virtual Tag metadata is updated. If <code>false</code> (default), all existing metadata and values are overridden. If <code>true</code>, the payload is merged with existing data instead of replacing it.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="Errors" %}

| 400           | Bad Request        |
| ------------- | ------------------ |
| 401           | Unauthorized       |
| 429           | Too many requests  |
| 503           | Server unavailable |
| 504           | Gateway Timeout    |
| {% endtab %}  |                    |
| {% endtabs %} |                    |

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.