# Virtual Tag Metadata API V2 (Beta) The Finout Virtual Tag Metadata API V2 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. *** ### Prerequisites Before using the Virtual Tag Metadata API V2, [generate a Finout API token](https://docs.finout.io/api/finout-api/generate-an-api-token) and include the following headers in every request: * `x-finout-client-id` * `x-finout-secret-key` The same credentials are used across all Finout API endpoints. You must also obtain the Virtual Tag ID before calling either endpoint. Use [GET /v2/virtual-tags](https://docs.finout.io/api/finout-api/finout-api-v2/virtual-tags-api-v2-beta) to retrieve your Virtual Tag IDs. *** ### Rate Limits | Route | Rate Limit | | ------------------------------------ | ------------- | | `GET /v2/virtual-tags/{id}/metadata` | 100 req / min | | `PUT /v2/virtual-tags/{id}/metadata` | 100 req / min | *** ### `GET` /Virtual Tag Metadata Returns a list of virtual tag values and their corresponding metadata. **Request** ``` GET https://app.finout.io/v2/virtual-tags/{id}/metadata ``` **Path parameter** | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------------- | | `id` | string | The ID of the Virtual Tag. Obtain this from `GET /v2/virtual-tags`. | **Response** 200 — Success ```json { "requestId": "103774e3-fee4-482a-9535-ddc5f09e9bee", "data": { "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" } } } } } ``` **Response when no metadata has been set:** ```json { "requestId": "63912df4-ad00-42cc-b5f8-05daa1584b09", "data": { "metadata": {} } } ``` Returns a JSON object with the following properties: | Field | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `requestId` | Unique identifier for the API request. | | `data.metadata` | Map of Virtual Tag values to their associated metadata. Empty object `{}` if no metadata has been set. | | `data.metadata.[value].groups` | Array of group IDs assigned to this value. | | `data.metadata.[value].customMetadata` | Key-value pairs of custom metadata attached to this value. | | `data.metadata.[value].endpoints` | Array of endpoint IDs assigned to this value. | **Error responses** | Code | Description | | ---- | ------------------ | | 400 | Bad Request | | 401 | Unauthorized | | 429 | Too many requests | | 503 | Server unavailable | | 504 | Gateway Timeout | *** ### `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. **Request** ``` PUT https://app.finout.io/v2/virtual-tags/{id}/metadata ``` **Path parameter** | Parameter | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------- | | `id` | string | The ID of the Virtual Tag to update. Obtain this from `GET /v2/virtual-tags`. | **Request body parameters** | 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 endpoint cannot include dots. See [Virtual Tags](https://docs.finout.io/user-guide/inform/virtual-tags). | | `customMetadata` | object | Any type of metadata to attach to the virtual tag value. You must specify the custom metadata key and value. Example: set `"owner"` as the key and `"owner_name"` as the value to assign an owner to a virtual tag value. See [Financial Plans](https://docs.finout.io/user-guide/inform/financial-plans). | | `groups` | array | The group for this specific value. You can use one or more groups. To get account group IDs, contact your customer success representative. See [Financial Plans](https://docs.finout.io/user-guide/inform/financial-plans). | | `endpoints` | array | An endpoint for this specific value. You can set one or more endpoints. Example: if the virtual tag value is "app team," provide the endpoint ID of the app team. To get a list of your account's endpoints, see [Endpoint API](https://docs.finout.io/api/finout-api/finout-api-v1/endpoint-api-v1). See [Reports](https://docs.finout.io/user-guide/operate/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. | **Use case example** 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. ### Option 1: Replace all (default) Omitting `mergeValuesAndMetadata` or setting it to `false` replaces all existing metadata for the Virtual Tag. **Request body example** ```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" } } } ``` **Response** 200 — Success ```json { "requestId": "210f5b74-e8b8-45a4-82b7-fd6274b83601", "data": { "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" } } }, "virtualTagId": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89" } } ``` Returns a JSON object with the following properties: * **requestId** — The unique identifier for the API request. * **data.metadata** — The updated map of virtual tag values to their associated metadata. * **data.virtualTagId** — The ID of the virtual tag that was updated. ### Option 2: Merge Setting `mergeValuesAndMetadata: true` merges the payload into existing metadata instead of replacing it. Useful for adding or updating a single value without touching the others. **Request body example** ```json { "App Team": { "customMetadata": { "owner": "Alice", "costCenter": "platform" }, "mergeValuesAndMetadata": true } } ``` **Response** 200 — Success ```json { "requestId": "a4c91b37-12de-4f8a-b3c2-9d8e7f123456", "data": { "metadata": { "App Team": { "groups": [ "d704e672-b33c-4fda-b4fc-bde7a8774de4" ], "customMetadata": { "owner": "Alice", "costCenter": "platform" }, "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" } } }, "virtualTagId": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89" } } ``` **Error responses** | Code | Description | | ---- | ------------------ | | 400 | Bad Request | | 401 | Unauthorized | | 429 | Too many requests | | 503 | Server unavailable | | 504 | Gateway Timeout | *** ### FAQ **What are the rate limits for V2?** Both Virtual Tag Metadata API V2 endpoints are limited to 100 requests per minute, applied per route per account. If you exceed the limit, you will receive a `429 Too Many Requests` response. Wait before retrying. **Does `PUT` always overwrite all existing metadata?** By default, yes — a `PUT` request replaces all existing metadata for the virtual tag. To merge your payload with existing data instead of replacing it, set `mergeValuesAndMetadata` to `true` in your request body. **How do I get a Virtual Tag ID?** Query `GET /v2/virtual-tags` to retrieve a list of your virtual tags and their IDs. See [Virtual Tags API V2](/api/finout-api/finout-api-v2/virtual-tags-api-v2-beta.md). **How do I get group IDs for the `groups` field?** Group IDs are account-specific. Contact your customer success representative to retrieve them. **Where is metadata used in Finout?** Currently, virtual tag value metadata is used in [Financial Plans](https://docs.finout.io/user-guide/inform/financial-plans). Groups and custom metadata set here are available when configuring financial plan line items. **Should I use V1 or V2?** Use V2 for all new integrations. V1 remains available but V2 offers higher rate limits and continued investment going forward. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.finout.io/api/finout-api/finout-api-v2/virtual-tag-metadata-api-v2-beta.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.