Tags

Tags are flexible metadata elements that can be associated with voucher statements, allowing for additional categorization and filtering of financial data.

Endpoints

List Tags

GET /api/v2/tags

Retrieves a paginated list of tags.

Query Parameters

Response

{
  "data": [
    {
      "id": 123,
      "name": "Travel Expenses",
      "client_account_id": 456,
      "sequence_number": 1,
      "is_active": true,
      "created_at": "2024-04-15T10:00:00Z",
      "updated_at": "2024-04-15T10:00:00Z",
      "created_by_id": 789,
      "updated_by_id": 789
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Get Tag

GET /api/v2/tags/{id}

Retrieves a specific tag by ID.

Query Parameters

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T10:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Create Tag

POST /api/v2/tags

Creates a new tag.

Request Body

Example Request

{
  "name": "Travel Expenses",
  "client_account_id": 456
}

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T10:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Update Tag

PUT|POST /api/v2/tags/{id}

Updates an existing tag. Only the fields present in the body are applied, so name and is_active can be sent on their own.

client_account_id may be sent, but only with the tag’s current value — changing it is rejected with tag.client_account_immutable.

Request Body

Example Request

{
  "name": "International Travel"
}

Response

{
  "id": 123,
  "name": "International Travel",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T15:30:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivate Tag

DELETE /api/v2/tags/{id}

Deactivates a tag by setting its is_active status to false. The tag record is preserved for historical purposes.

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": false,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T16:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivation Validation

When attempting to deactivate a tag, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory tag dimensions have non-zero balances for this specific tag.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": {
        "code": "common.validation_error",
        "message": "Cannot deactivate tag: account 1500: 3200.00, account 2400: -800.00",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

This validation ensures that tags cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Relationships

Statistics are limited to balance-sheet accounts (account code 2999 and below). Balances for income-statement accounts (account code 3000 and above) are not included, and accounts whose balance for the tag is zero are left out of balances entirely.

Example Response with Statistics

GET /api/v2/tags/123?with=statistics

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": true,
  "created_at": "2024-04-15T10:00:00Z",
  "updated_at": "2024-04-15T10:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789,
  "statistics": {
    "balances": [
      { "account_code": "1500", "balance": "3200.00" },
      { "account_code": "2400", "balance": "-800.00" }
    ]
  }
}

Voucher Statement Integration

Tags can be associated with voucher statements, allowing for multiple tags per voucher.

Example Voucher Statement with Tags

{
  "id": 456,
  "voucher_id": 789,
  "client_account_id": 456,
  "tags": [
    {
      "id": 123,
      "name": "Travel Expenses",
      "sequence_number": 1,
      "client_account_id": 456
    },
    {
      "id": 124,
      "name": "Marketing",
      "sequence_number": 2,
      "client_account_id": 456
    }
  ],
  "purpose": "Business trip to client meeting",
  "additional_information": "Annual strategic planning session"
}

Error Responses

Errors use the standard v2 envelope ({"error": {"code", "message", "request_id"}}) — see Error Handling.

Business Rules

1. Tags are associated with a specific client account
2. Users must have access to the client account to manage its tags
3. The client_account_id cannot be changed after tag creation
4. Each tag is automatically assigned a unique sequence number within its client account
5. Tags can be associated with multiple voucher statements (many-to-many relationship)
6. Tag names must be unique within a client account; the check runs when a tag is created, not when one is renamed
7. Creation and update timestamps and user IDs are automatically tracked

Common Use Cases

1. Categorizing expenses by purpose or project
2. Adding supplementary search criteria to vouchers
3. Grouping related vouchers for reporting
4. Creating custom dimensions for financial analysis

Best Practices

1. Use concise, descriptive tag names
2. Maintain consistent naming conventions
3. Avoid creating too many similar tags
4. Use tags as an additional dimension rather than replacing existing categorization systems
5. Consider creating a tagging strategy for consistency across the organization