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

{
  "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:

{
  "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.
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.
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.
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. 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.

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

{
  "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

{
  "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

{
  "App Team": {
    "customMetadata": {
      "owner": "Alice",
      "costCenter": "platform"
    },
    "mergeValuesAndMetadata": true
  }
}

Response

200 — Success

{
  "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.

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