Virtual Tag Metadata
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.
Configuring API Access
Finout API is fully secured using a secret key and client token, which can be managed from your Finout account. Your Finout account allows for five concurrent requests per API key. When you generate the API token, it creates both a secret key and a client ID (token). These parameters will be passed in the Authorization header when invoking any Finout API methods.
Important: Copy and save your Client ID and Secret Key for future use. They will only appear once and will not show again.
To configure API access:
Select your profile from the user dropdown on the top left of any screen in Finout.
Click Admin Portal. The Profile window appears.
Select API Tokens. The API Token screen appears.
Click Generate Token. The Generate Token window appears.
Enter a Description, choose a role, choose token expiration, and click Create. Your token is generated.
Copy the Client ID and the Secret Key, which won't be accessible later, and then click Done.
Add the Client ID and Secret Key in Headers when invoking any of the Finout endpoints:
x-finout-client-id
x-finout-secret-key
GET Virtual Tag Metadata
Description
Returns a list of virtual tag values and their corresponding metadata. Documentation to learn more about utilizing metadata in financial plans is coming soon.
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.
Base URL
The base URL for all API requests is: https://app.finout.io/v1/
Endpoints
GET/virtual-tags/{vtag_id}/metadata
Parameters
None
Response
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.
Example
Request:
https://app.finout.io/v1/virtual-tags/{vtag_id}/metadata
Response:
{
"requestId": "060ed9c0-6bb7-4132-a88a-6e7f4fead7d5",
"metadata": {
"App Team": {
"groups": [
"d704e672-b33c-4fda-b4fc-bde7a8774de4"
],
"customMetadata": {
"owner": "Dave"
}
},
"Data Team": {
"groups": [
"f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
],
"customMetadata": {
"owner": "Dan"
}
},
"DevOps Team": {
"groups": [
"4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
],
"customMetadata": {
"owner": "Sam"
}
}
}
}
PUT virtual tag metadata
Description
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.
Base URL
The base URL for all API requests is: https://app.finout.io/v1/
Endpoint
PUT/virtual-tags/{vtag_id}/metadata
Parameters
Parameter | Type | Description |
Virtual Tag Value | String | The object that defines the value for the virtual tag. This can be of any value. |
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.
|
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. |
endpoints
Note: | Array | An endpoint of this specific value. You can set one or more endpoints.
|
Response
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.
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.
Request:
https://app.finout.io/v1/virtual-tags/{vtag_id}/metadata
Body of the Request:
{
"App Team": {
"groups": ["d704e672-b33c-4fda-b4fc-bde7a8774de4"],
"customMetadata": {
"owner": "Dave"
}
},
"Data Team": {
"groups": ["f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"],
"customMetadata": {
"owner": "Dan"
}
},
"DevOps Team": {
"groups": ["4b6f659e-6a7a-4dc4-975c-30a641f0a42b"],
"customMetadata": {
"owner": "Sam"
}
}
}
Response:
{
"requestId": "af50e5cb-a503-46c3-bfb3-83a2cd81b8ac",
"metadata": {
"App Team": {
"groups": [
"d704e672-b33c-4fda-b4fc-bde7a8774de4"
],
"customMetadata": {
"owner": "Dave"
}
},
"Data Team": {
"groups": [
"f9e4a3f1-b8e4-4ff6-8307-e414dfc69ddb"
],
"customMetadata": {
"owner": "Dan"
}
},
"DevOps Team": {
"groups": [
"4b6f659e-6a7a-4dc4-975c-30a641f0a42b"
],
"customMetadata": {
"owner": "Sam"
}
}
},
"request": {
"virtualTagId": "4da98beb-e393-417b-9729-1781aac55e2d"
}
}
Errors
400 | Bad Request |
401 | Unauthorized |
429 | Too many requests |
503 | Server unavailable |
504 | Gateway Timeout |