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,
      "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": 50,
    "records": 1
  }
}

Get Tag

GET /api/v2/tags/{id}

Retrieves a specific tag by ID.

Response

{
  "id": 123,
  "name": "Travel Expenses",
  "client_account_id": 456,
  "sequence_number": 1,
  "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,
  "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 /api/v2/tags/{id}

Updates an existing tag.

Request Body

Example Request

{
  "name": "International Travel"
}

Response

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

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

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