--- agentTools: projectIndex: https://api-doc.hostex.io/llms.txt --- # Query Incomes & Expenses Query income and expense entries (also known as `transactions`) recorded against the operator, properties or reservations. The response provides each entry with its categorization (`item_id` / `item_name`) and payment method (`payment_method_id` / `payment_method_name`). The values of `item_id` and `payment_method_id` reference the dictionaries returned by `GET /income_items`, `GET /expense_items`, `GET /income_methods` and `GET /expense_methods` (which dictionary applies depends on `direction`). # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Hostex API", "description": "API for integration with Hostex", "version": "3.0.0" }, "servers": [ { "url": "https://api.hostex.io/v3", "description": "Hostex API Server" } ], "tags": [ { "name": "Incomes & Expenses", "description": "Income and expense entries (transactions) plus the dictionaries used to categorize them." } ], "paths": { "/transactions": { "get": { "summary": "Query Incomes & Expenses", "description": "Query income and expense entries (also known as `transactions`) recorded against the operator, properties or reservations.\n\nThe response provides each entry with its categorization (`item_id` / `item_name`) and payment method (`payment_method_id` / `payment_method_name`). The values of `item_id` and `payment_method_id` reference the dictionaries returned by `GET /income_items`, `GET /expense_items`, `GET /income_methods` and `GET /expense_methods` (which dictionary applies depends on `direction`).", "operationId": "query-transactions", "tags": [ "Incomes & Expenses" ], "security": [ { "HostexAccessToken": [] } ], "x-mcp": { "exposed": true, "tool_name": "search_transactions", "description": "Query transaction entries (income / expense ledger). Filter by direction (`income` / `expense`), linked reservation (`reservation_code`, or the deprecated `stay_code`), linked property (`property_id`), date range, etc.; or pass `id` directly to fetch a single entry. Returns each entry's amount, currency, item (`item_id` / `item_name`), payment method, and linked object. `start_date` / `end_date` are optional when filtering by `id`.", "intent_examples": [ "All income this month", "Expenses for Coastal Villa #1 this month", "All transactions related to reservation ABC123", "Show me the details of transaction 12345" ], "category": "finance", "read_only": true, "since_version": "3.4.0" }, "parameters": [ { "name": "id", "in": "query", "description": "Internal id of a specific transaction entry. When supplied, returns at most one matching entry under the current operator; `start_date` and `end_date` may then be omitted.", "required": false, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Start of the action time range, inclusive. Format `YYYY-MM-DD`. Interpreted in the operator's configured timezone. Required unless `id` is supplied.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End of the action time range, inclusive. Format `YYYY-MM-DD`. Interpreted in the operator's configured timezone. The range from `start_date` to `end_date` cannot exceed 366 days. Required unless `id` is supplied.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "offset", "in": "query", "description": "The starting point from which to begin returning results.", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "The maximum number of results to return. The maximum value is 100.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "property_id", "in": "query", "description": "Filter entries linked to the given property id (either directly recorded against the property, or indirectly through a reservation on this property).", "required": false, "schema": { "type": "integer" } }, { "name": "reservation_code", "in": "query", "description": "Filter entries linked to the given reservation (the `reservation_code` returned by `GET /reservations`). Entries are always recorded against the whole reservation, so on a multi-unit reservation this returns the entries of every unit. Passing the `stay_code` of any unit is also accepted and resolves to the same reservation.", "required": false, "schema": { "type": "string" } }, { "name": "stay_code", "in": "query", "description": "Deprecated alias of `reservation_code`, kept for backward compatibility. Any stay code is resolved to its reservation, so this never narrows the result to a single unit. Use `reservation_code`, or `property_id` when you want the entries of one property.", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Filter by direction: `income` for money received, `expense` for money spent.", "required": false, "schema": { "type": "string", "enum": [ "income", "expense" ] } }, { "name": "item_id", "in": "query", "description": "Filter by item id (the categorization of the entry). For income entries the id refers to `GET /income_items`; for expense entries it refers to `GET /expense_items`.", "required": false, "schema": { "type": "integer" } }, { "name": "payment_method_id", "in": "query", "description": "Filter by payment method id. For income entries the id refers to `GET /income_methods`; for expense entries it refers to `GET /expense_methods`.", "required": false, "schema": { "type": "integer" } }, { "name": "currency", "in": "query", "description": "Filter by currency code. See [Supported Currencies](/reference/supported-currencies) for more information.", "required": false, "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "description": "Substring match on the entry `note`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of transaction entries with their details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CommonResponse" }, { "required": [ "data" ], "properties": { "data": { "required": [ "transactions", "total" ], "properties": { "transactions": { "description": "List of transaction entries.", "type": "array", "items": { "type": "object", "required": [ "id", "direction", "amount", "currency" ], "properties": { "id": { "description": "Unique identifier of the transaction entry.", "type": "integer", "format": "int64" }, "direction": { "description": "Whether the entry represents money received (`income`) or spent (`expense`).", "type": "string", "enum": [ "income", "expense" ] }, "amount": { "description": "Absolute amount of the entry, always non-negative; use `direction` to distinguish income from expense.", "type": "number" }, "currency": { "description": "The currency code of the entry. See [Supported Currencies](/reference/supported-currencies) for more information.", "type": "string" }, "status": { "description": "Payment status of the entry.", "type": "string", "enum": [ "paid", "outstanding" ] }, "action_at": { "description": "When the action took place, in ISO 8601 (UTC).", "type": "string", "nullable": true }, "item_id": { "description": "The id of the item categorization. References `GET /income_items` when `direction` is `income`, or `GET /expense_items` when `direction` is `expense`.", "type": "integer", "nullable": true }, "item_name": { "description": "Human-readable name of the item, resolved against the item dictionary at the time of the request. May be a localized name for system-default items, or the operator's custom name.", "type": "string", "nullable": true }, "payment_method_id": { "description": "The id of the payment method. References `GET /income_methods` when `direction` is `income`, or `GET /expense_methods` when `direction` is `expense`.", "type": "integer", "nullable": true }, "payment_method_name": { "description": "Human-readable name of the payment method.", "type": "string", "nullable": true }, "note": { "description": "Free-form note attached to the entry.", "type": "string" }, "operator_name": { "description": "Display name of the user who created the entry, or `System` for entries created by automated processes.", "type": "string" }, "link_type": { "description": "What the entry is linked to: `property` (a specific property), `reservation` (a specific stay), or `operator` (the operator account, not tied to any property or reservation).", "type": "string", "enum": [ "property", "reservation", "operator" ] }, "property_id": { "description": "Id of the related property, if any. For reservation-linked entries this resolves to the stay's property; for property-linked entries this is the property itself; null for operator-linked entries.", "type": "integer", "nullable": true }, "property_title": { "description": "Title of the related property.", "type": "string", "nullable": true }, "reservation_code": { "description": "The `reservation_code` of the reservation the entry is linked to. Null when not linked to a reservation.", "type": "string", "nullable": true }, "stay_code": { "description": "Deprecated alias of `reservation_code`, kept for backward compatibility, and always identical to it. It is the reservation's code, not the stay code that was submitted when the entry was created.", "type": "string", "nullable": true, "deprecated": true }, "created_at": { "description": "When the entry was created, in ISO 8601 (UTC).", "type": "string", "nullable": true }, "updated_at": { "description": "When the entry was last updated, in ISO 8601 (UTC).", "type": "string", "nullable": true } } } }, "total": { "description": "Total number of entries matching the filters.", "type": "integer" } }, "type": "object" } }, "type": "object" } ] } } } } } } } }, "components": { "schemas": { "CommonResponse": { "required": [ "request_id", "error_code", "error_msg" ], "properties": { "request_id": { "description": "Unique identifier for the request.", "type": "string" }, "error_code": { "description": "Numeric error code representing the status of the response. A value of `200` indicates success.
See the [Error Codes](/reference/errors#error-code-reference) section for more information.", "type": "integer", "example": 200 }, "error_msg": { "description": "Message detailing the status of the response.", "type": "string", "example": "Done." } }, "type": "object" } }, "securitySchemes": { "HostexAccessToken": { "type": "apiKey", "description": "Access token to authenticate the request.", "name": "Hostex-Access-Token", "in": "header" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 101, "1": 185, "2": 233, "3": 171, "4": 120, "5": 81, "6": 121, "7": 0, "8": 107, "9": 167, "10": 90, "11": 156 } } } ```