# Transaction Tags V1 — Developer Guide

> **Reference:** [Transaction Tags (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/transactiontags-(v1))


Transaction tags are short text labels that can be attached to payment and adjustment transactions for categorization and reporting purposes. Tags are referenced by their ID when linking them to a transaction via the `transactionTags` field on [Patient Payments](/publicapi/endpoints/transactions-patientpayments-v1) and [Adjustment Transactions](/publicapi/endpoints/transactions-adjustments-v1).

Two types of tags exist:

| `tagType` | Used On |
|  --- | --- |
| `PAYMENT_TAG` | Patient payment transactions |
| `ADJUSTMENT_TAG` | Adjustment transactions (charge and credit) |


## GET — Bulk List Transaction Tags

Returns a paginated list of transaction tags filtered by the provided criteria.

> **⚠️ Rate Limited:** This endpoint is rate limited. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) for details.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `Organization-ID` | header | Yes | string | The organization ID |
| `filter` | query | No | string | Filter criteria (see filter keys below). If omitted, a default date-limiting filter is applied automatically. |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |
| `page` | query | No | string | Page number for pagination |
| `pageSize` | query | No | string | Number of records per page |
| `lastId` | query | No | string | Largest tag ID from the previous page, used for efficient pagination |


### Filter Keys

| Filter Key | Operators | Example |
|  --- | --- | --- |
| `id` | `->` | `?filter=id->[1000000020702,1000000020703]` |
| `tagText` | `==`, `!=`, `~=`, `<>=` | `?filter=tagText==Insurance` |
| `tagType` | `==`, `!=` | `?filter=tagType==PAYMENT_TAG` |


#### `tagText` Operator Details

| Operator | Behavior |
|  --- | --- |
| `==` | Exact match |
| `!=` | Not equal |
| `~=` | Starts with (prefix search) |
| `<>=` | Contains (substring search) |


### Example Requests

Fetch all payment tags:

```
GET /api/v1/transactiontags?filter=tagType==PAYMENT_TAG
```

Search for tags starting with "Insurance":

```
GET /api/v1/transactiontags?filter=tagText~=Insurance
```

Fetch specific tags by ID:

```
GET /api/v1/transactiontags?filter=id->[1000000020702,1000000020703]
```

## GET — Transaction Tag by ID

Returns a single transaction tag by its ID.

### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `transactionTagId` | path | Yes | integer | The ID of the transaction tag |
| `Organization-ID` | header | Yes | string | The organization ID |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |


### Example Request

```
GET /api/v1/transactiontags/1000000020702
```

## POST — Create Transaction Tag

Creates a new transaction tag. All three fields are required.

### Scenario 1 — POST: Create a Payment Tag

Use this scenario to create a tag that can be attached to patient payment transactions.

#### Required Fields

| Field | Type | Description |
|  --- | --- | --- |
| `tagText` | string | The tag label. Min 1, max 30 characters. |
| `isPredefined` | boolean | Whether this tag is a predefined system tag (`true`) or a custom tag (`false`). |
| `tagType` | string | Must be `"PAYMENT_TAG"` |


#### Example Request Body

```json
{
  "tagText": "Online Payment",
  "isPredefined": false,
  "tagType": "PAYMENT_TAG"
}
```

### Scenario 2 — POST: Create an Adjustment Tag

Use this scenario to create a tag that can be attached to charge or credit adjustment transactions.

#### Required Fields

| Field | Type | Description |
|  --- | --- | --- |
| `tagText` | string | The tag label. Min 1, max 30 characters. |
| `isPredefined` | boolean | Whether this is a predefined tag. |
| `tagType` | string | Must be `"ADJUSTMENT_TAG"` |


#### Example Request Body

```json
{
  "tagText": "Write-Off",
  "isPredefined": true,
  "tagType": "ADJUSTMENT_TAG"
}
```

## DELETE — Delete Transaction Tag

Deletes a specific transaction tag by ID.

> **Note:** Deleting a tag that is currently referenced by transaction records may affect reporting and filtering by that tag.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `transactionTagId` | path | Yes | integer | The ID of the transaction tag to delete |
| `Organization-ID` | header | Yes | string | The organization ID |


### Example Request

```
DELETE /api/v1/transactiontags/1000000020702
```

## Streaming

Transaction tags are streamable via the [Streaming API](https://papidocs.hs1api.com/publicapi/api-consumer-guide#streaming). Unlike transaction records (which use `TransactionV1`), transaction tags have their own dedicated domain type: **`TransactionTagV1`**.

### Routing Key Format

```
organizationId.locationId.TransactionTagV1.operationType
```

### Example Routing Keys

Listen for all transaction tag events across all locations:

```
66d22762060811049b50d085.*.TransactionTagV1.*
```

Listen for creates only:

```
66d22762060811049b50d085.*.TransactionTagV1.CREATE
```

Listen for deletes only at a specific location:

```
66d22762060811049b50d085.1000000000123.TransactionTagV1.DELETE
```

### Operations Emitted

| Operation | When |
|  --- | --- |
| `CREATE` | When a new transaction tag is created (POST) |
| `UPDATE` | When a transaction tag is modified |
| `DELETE` | When a transaction tag is deleted (DELETE) |


## Response Structure

A successful `200`/`201` response returns:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | The created, retrieved, or deleted tag |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Field-level errors |


For bulk GET, `data` is an array and includes `meta.pagination`.

### `data` Object — Transaction Tag Fields

| Field | Type | Read-Only | Description |
|  --- | --- | --- | --- |
| `id` | integer | Yes | Unique tag ID |
| `tagText` | string | No | Tag label (1–30 characters) |
| `isPredefined` | boolean | No | Predefined system tag flag |
| `tagType` | string | No | `PAYMENT_TAG` or `ADJUSTMENT_TAG` |


## Errors & Warnings Reference

details
summary
strong
HTTP Status Code Errors
— click to expand
#### `400` — Bad Request

The request body or parameters are invalid. See field-level errors below.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Fix** | Provide a valid Bearer token in the `Authorization` header. |


#### `403` — Forbidden

|  |  |
|  --- | --- |
| **Message** | The request is understood, but it has been refused or access is not allowed. |
| **Why** | Token lacks `model:read` (GET) or `model:write` (POST/DELETE) scope. |
| **Fix** | Request the appropriate scope for the operation. |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No transaction tag exists for the given `transactionTagId` within your organization. |
| **Fix** | Confirm the `transactionTagId` is correct and belongs to your organization. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Fix** | Retry the request. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Fix** | Implement exponential backoff. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting). |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Fix** | Retry. If the issue persists, contact support. |


details
summary
strong
Field-Level Validation Errors
— click to collapse
### `tagText`

**Error:** Missing or invalid `tagText`.

|  |  |
|  --- | --- |
| **Why** | `tagText` was not provided, is empty, or exceeds 30 characters. |
| **Fix** | Provide a string between 1 and 30 characters. |


### `tagType`

**Error:** Invalid `tagType`.

|  |  |
|  --- | --- |
| **Why** | The `tagType` value is not one of the recognized enum values. |
| **Fix** | Use `"PAYMENT_TAG"` or `"ADJUSTMENT_TAG"`. |


### `isPredefined`

**Error:** Missing `isPredefined`.

|  |  |
|  --- | --- |
| **Why** | The `isPredefined` field was not included in the request body. |
| **Fix** | Include `isPredefined` as `true` or `false`. |