Virtual Tags API

The Virtual Tags API allows you to create, retrieve, update, and delete Virtual Tag configurations. Virtual Tags organize and categorize data based on custom rules and filters.

Note: The Reallocation and MegaBill Key segmentation are currently unsupported in the Virtual Tag API.

GET/Virtual Tags

Retrieves all virtual tag configurations.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

Request https://app.finout.io/v1/virtual-tags

Response

200

{
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "requestId": "6e0f327e-9948-440b-b577-d0203aa374e9",
    "virtualTags": [
        {
            "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
            "createdBy": "[e-mail]",
            "name": "Demo Feature cost",
            "rules": [
                {
                    "to": "demo",
                    "filters": {
                        "costCenter": "AWS",
                        "key": "f_inst_type",
                        "displayName": "Instance Type",
                        "operator": "is",
                        "value": [
                            "a1.2xlarge",
                            "a1.large",
                            "a1.medium"
                        ]
                    }
                }
            ],
            "category": "Project",
            "createdAt": "Sun Sep 29 2024 08:20:37 GMT+0000 (Greenwich Mean Time)",
            "updatedAt": "Tue Oct 29 2024 12:13:50 GMT+0000 (Greenwich Mean Time)",
            "updatedBy": "[e-mail]",
            "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89",
            "defaultValue": "Untagged"
        },
        {
            "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
            "name": "Org/Department",
            "rules": [
                {
                    "to": "TLV",
                    "filters": {
                        "costCenter": "Virtual Tags",
                        "key": "cc7e8b30-b141-496b-82b5-ddd4d535c79d",
                        "displayName": "Group Names",
                        "operator": "oneOf",
                        "value": [
                            "Data",
                            "Core"
                        ]
                    }
                },
                {
                    "to": "NYC",
                    "filters": {
                        "costCenter": "Virtual Tags",
                        "key": "cc7e8b30-b141-496b-82b5-ddd4d535c79d",
                        "displayName": "Group Names",
                        "operator": "oneOf",
                        "value": [
                            "Legacy",
                            "Infra",
                            "Front End"
                        ]
                    }
                }
            ],
            "createdBy": "Maks Kogan",
            "updatedBy": "[e-mail]",
            "createdAt": "Tue Oct 17 2023 18:08:17 GMT+0000 (Greenwich Mean Time)",
            "updatedAt": "Fri Aug 16 2024 18:00:49 GMT+0000 (Greenwich Mean Time)",
            "category": "Teams",
            "id": "4f816fc1-6b3a-4902-b6b5-9759ba5ca83c",
            "defaultValue": "Untagged"
        }
    ]
}

Common Errors

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404- Not Found

429 - Too Many Request

500 - Internal Server Error

422

Unprocessable Request

POST /Virtual Tag

Create a new virtual tag.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

Request

https://app.finout.io/v1/virtual-tags

Query Request

{
  "name": "Demo Feature cost2222",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "f_inst_type",
        "displayName": "Instance Type",
        "operator": "is",
        "value": [
          "a1.2xlarge",
          "a1.large",
          "a1.medium"
        ]
      }
    }
  ],
  "defaultValue": "Untagged"
}

Body parameters

name	string	The name of the virtual tag.
rules	array	An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.
defaultValue	string	The defaultValue objec

Response

200

{
    "requestId": "5f8ae41e-02fb-4a03-900e-7451dc3d073f",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "category": "Project",
    "endpoints": [],
    "allocations": [],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

PUT/Virtual Tags

Update a current virtual tag.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

• Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter	Type	Description
ID	String	The ID of the Virtual Tag is to be updated.

Request Query

{
  "name": "Demo Feature cost2223",
  "rules": [
    {
      "to": "Fea",
      "filters": {
        "costCenter": "AWS",
        "key": "f_inst_type",
        "displayName": "Instance Type",
        "operator": "is",
        "value": [
          "NEW1",
          "NEW2",
          "NEW3"
        ]
      }
    }
  ],
  "defaultValue": "Untagged"
}

Request Body Parameters

name	string	The name of the Virtual Tag.
rules	array	An array of rules defines the filters and conditions for the virtual tag. See Virtual Tag Objects.
defaultValue	string	The defaultValue object.

Response

200

{
    "requestId": "c17dc36d-6007-48f6-a06f-35ccb74f58a8",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "Finout",
    "name": "Demo Feature cost2223",
    "archiverIgnore": false,
    "rules": [
        {
            "to": "Fea",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "NEW1",
                    "NEW2",
                    "NEW3"
                ]
            }
        }
    ],
    "category": "Project",
    "endpoints": [],
    "allocations": [],
    "createdAt": "Sun Nov 17 2024 11:55:11 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Mon Nov 18 2024 08:33:52 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "Finout",
    "id": "d1a99df2-dfb3-4da6-8877-91a655d5deb8",
    "defaultValue": "Untagged"
}

GET/Virtual Tag By ID

Retrieves the specified Virtual Tag configuration.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

• Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path Parameter

Parameter	Type	Description
id	String	The id of the Virtual Tag to retrieve.

Response

200

{
    "requestId": "168b62f4-92f7-4871-aaf9-04ce725fc303",
    "accountId": "e6ad4c08-9ecd-4592-be61-7a13ad456259",
    "createdBy": "[e-mail]",
    "name": "Demo Feature cost",
    "rules": [
        {
            "to": "demo",
            "filters": {
                "costCenter": "AWS",
                "key": "f_inst_type",
                "displayName": "Instance Type",
                "operator": "is",
                "value": [
                    "a1.2xlarge",
                    "a1.large",
                    "a1.medium"
                ]
            }
        }
    ],
    "category": "Project",
    "createdAt": "Sun Sep 29 2024 08:20:37 GMT+0000 (Greenwich Mean Time)",
    "updatedAt": "Tue Oct 29 2024 12:13:50 GMT+0000 (Greenwich Mean Time)",
    "updatedBy": "[e-mail]",
    "id": "d8026cec-6d3b-4c54-87f7-6ea815aa3b89",
    "defaultValue": "Untagged"
}

DELETE/Virtual Tag

Deletes the specified Virtual Tag.

Prerequisites

• Generate a Client ID and Secret Key from Finout to add in Headers.

• Get a virtual tag ID.

Request

https://app.finout.io/v1/virtual-tags/{id}

Path parameter

Parameter	Type	Description
id	string	The id of the Virtual Tag to delete.

Response

The Virtual tag is deleted.

Virtual Tags Objects

The Virtual Tags object represents a configuration used for resource allocation and filtering. It contains the following fields:

Field	Type	Description	Example Value
accountId	string	The unique identifier of the account is associated with the Virtual Tag.	"e12498cc-594a-4740-94a5-8324e7399bb2"
name	string	The name of the Virtual Tag.	"nir test"
rules	array	An array of RULE objects that defines the filtering criteria for the Virtual Tag.	See the table below.
category	string	The category of the Virtual Tag.	"Project"
createdBy	string	The name of the user who created the Virtual Tag.	"Nir"
updatedBy	string	The name of the user who last updated the Virtual Tag.	"Asaf Liveanu"
defaultValue	string	An object defining the default value for the Virtual Tag.	“untagged”
createdAt	string	The date and time when the Virtual Tag was created.	"Tue May 16 2023 13:15:53 GMT+0000 (Greenwich Mean Time)"
updatedAt	string	The date and time when the Virtual Tag was last updated.	"Sat Jun 10 2023 16:06:25 GMT+0000 (Greenwich Mean Time)"
id	string	The unique identifier of the Virtual Tag.	"b11c9be2-b7a0-4209-a00e-44ac2ccce0f7"

“Rules” object definition

Field	Type	Description	Example Value
to	string	The destination or target for the filtered data.	"Data Team"
filters	object	An object containing the filter conditions for the rule.	See the table below.

Error Handling

The API returns standard HTTP error codes to indicate the success or failure of a request. The following common HTTP errors may be returned:

HTTP error codes

• 400 Bad Request: The request is malformed or missing the required parameters. Check the request structure carefully for syntax typos and resubmit the request.

• 401 Unauthorized: The request lacks valid authentication credentials. Ensure that you have added your credentials to the request header and resubmit your request. If this still doesn't work, contact Finout Support.

• 403 Forbidden: The request is understood, but the server refuses to fulfill it due to access restrictions. Contact Finout Support.

• 404 Not Found: The requested resource is not found. Resubmit the request with a valid resource ID.

• 429 Too Many Requests: The user has sent too many requests in a given period.

• 422 Unprocessable Request: Check the virtual tag composition and structures.

• 500 Internal Server Error: An unexpected error occurred on the server.