Skip to main content
All CollectionsAPI
Virtual Tag Metadata API
Virtual Tag Metadata API
Updated over a week ago

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:

  1. Select your profile from the user dropdown on the top left of any screen in Finout.

  2. Click Admin Portal. The Profile window appears.

  3. Select API Tokens. The API Token screen appears.

  4. Click Generate Token. The Generate Token window appears.

  5. Enter a Description, choose a role, choose token expiration, and click Create. Your token is generated.

  6. Copy the Client ID and the Secret Key, which won't be accessible later, and then click Done.

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

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": "ccffccb5-e8ce-4876-980e-1195077cd7f5",

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

}

}

}

}

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

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.
Limitation:
Virtual tag values in this specific endpoint cannot include dots.

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:
The ability to use the endpoint metadata in Finout is coming soon.

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.

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"

},

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

{

"requestId": "1eeee4d4-55fb-4452-8ea0-eef3e6371ba1",

"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

Did this answer your question?