# Travelotter API

> Travelotter is an enterprise travel expense management platform for Austrian and German companies.
> The REST API enables payroll integration (BMD, DATEV, RZL), data import/export, webhook delivery,
> and full travel lifecycle management including per diem calculations, receipts, and car allowances.

## Quick Start

Base URL: `https://api.travelotter.app/api/v1`
Auth: `x-api-key` header with key format `to_{live|test}_{prefix}{secret}`
Rate Limit: 100 req/min per API key, 10 req/min per IP (pre-auth)
Content-Type: `application/json`

All responses follow: `{"success": bool, "data": {...}, "metadata": {"request_id": "...", "timestamp": "..."}}`
Errors follow: `{"success": false, "error": {"code": "...", "message": "..."}, "metadata": {...}}`

## Travels & Expense Management

- [Manage Travels](https://travelotter.app/llms-full.txt#travels-crud): CRUD + PDF + validation + diem calculation (scope: travels:read/write)
- [Travel Stages](https://travelotter.app/llms-full.txt#travel-stages-crud): Time periods with locations, meals, night allowances (scope: travels:read/write)
- [Travel Receipts](https://travelotter.app/llms-full.txt#travel-receipts-crud): Receipts with VAT positions + file upload/download (scope: travels:read/write)
- [Car Allowances](https://travelotter.app/llms-full.txt#car-allowances-crud): Mileage tracking with route segments + calculation (scope: travels:read/write)
- [Travel Approvals](https://travelotter.app/llms-full.txt#travel-approvals): Approval workflow — approve/reject/comment (scope: travels:read/write)
- [Locations](https://travelotter.app/llms-full.txt#locations-crud): Address management with optional geocoding (scope: travels:read/write)
- [Regions](https://travelotter.app/llms-full.txt#regions): Region list for per diem rates by travel type (scope: travels:read)

## Payroll & Wage Types

- [Wage Type Transfers](https://travelotter.app/llms-full.txt#wage-type-transfers): Retrieve transfer positions for payroll (scope: wage_types:read)
- [Trigger Transfer](https://travelotter.app/llms-full.txt#wage-type-transfer-trigger): Trigger transfer for approved travels (scope: wage_types:write)
- [Wage Types CRUD](https://travelotter.app/llms-full.txt#wage-types-crud): Manage payroll categories (scope: wage_types:read/write)
- [Wage Type Sets](https://travelotter.app/llms-full.txt#wage-type-sets-crud): Group wage types with transfer settings (scope: wage_types:read/write)
- [Value Type Mappings](https://travelotter.app/llms-full.txt#value-type-wage-type-mappings): Map diem/night/mileage types to wage types (scope: wage_types:read/write)
- [Receipt Type Default Wage Types](https://travelotter.app/llms-full.txt#receipt-type-default-wage-types): Default wage type per receipt type (scope: wage_types:read/write)
- [VAT Rate Wage Types](https://travelotter.app/llms-full.txt#vat-rate-wage-type-mappings): Map VAT rates to wage types (scope: wage_types:read/write)

## Data Import

- [Import Persons](https://travelotter.app/llms-full.txt#persons-import): Batch import/update/deactivate employees (scope: persons:write)
- [Import Entities](https://travelotter.app/llms-full.txt#entities-import): Import cost centers, cost units, customers, groups, locations (scope: {entity}:write)

## Export & Files

- [Export Data](https://travelotter.app/llms-full.txt#exports): Execute exports with optional ZIP bundling of PDFs + receipts (scope: exports:execute)
- [Export Formats](https://travelotter.app/llms-full.txt#export-formats-crud): Configure CSV export columns, filters, aggregation (scope: exports:read/write)
- [Combined Formats](https://travelotter.app/llms-full.txt#combined-export-formats-crud): Bundle multiple formats into one export (scope: exports:read/write)
- [Download Files](https://travelotter.app/llms-full.txt#files-download): Get signed URLs for travel PDFs and receipt files (scope: files:read)

## Configuration

- [Receipt Types](https://travelotter.app/llms-full.txt#receipt-types-crud): Manage receipt categories — Taxi, Hotel, etc. (scope: receipt_types:read/write)
- [Receipt Countries](https://travelotter.app/llms-full.txt#receipt-country-configuration): Enable/disable countries for receipts (scope: receipt_types:read/write)
- [VAT Rates](https://travelotter.app/llms-full.txt#vat-rates): VAT rates per country with validity periods (scope: receipt_types:read/write)
- [Travel Type Assignments](https://travelotter.app/llms-full.txt#travel-type-assignments): Assign travel types to company (scope: travel_types:read/write)
- [Car Allowance Type Assignments](https://travelotter.app/llms-full.txt#car-allowance-type-assignments): Assign car allowance types (scope: car_allowance_types:read/write)
- [Additional Fields](https://travelotter.app/llms-full.txt#additional-fields-crud): Custom data fields for travels/receipts (scope: additional_fields:read/write)
- [Field Configurations](https://travelotter.app/llms-full.txt#field-configurations): Visibility and mandatory rules per action (scope: additional_fields:read/write)
- [Settings](https://travelotter.app/llms-full.txt#settings): Company feature flags with subscription gating (scope: settings:read/write)

## Webhooks & Monitoring

- [Trigger Webhook](https://travelotter.app/llms-full.txt#webhooks): Standard Webhooks compliant delivery with HMAC-SHA256 (scope: webhooks:execute)
- [API Logs](https://travelotter.app/llms-full.txt#api-request-logs): Query individual request logs (scope: logs:read)
- [Usage Statistics](https://travelotter.app/llms-full.txt#api-usage-statistics): Aggregated usage with latency percentiles (scope: logs:read)

## CLI (`to`) — Recommended for AI Agents

The `to` CLI wraps the entire API and is the recommended way for AI agents to interact with Travelotter.
It handles authentication (OS keychain), output formatting, pagination, and file downloads.

**Install** (requires Python 3.11+):
```bash
pip install https://api.travelotter.app/storage/v1/object/public/cli-releases/latest/travelotter_cli-latest-py3-none-any.whl
```

**Setup**: `to config login` (stores API key in OS keychain)

**Commands:**
- `to travels list|get|create|delete|pdf|validate|calculate|values` — Full travel lifecycle
- `to exports run` — Execute exports (CSV/ZIP with PDFs and receipts)
- `to wage-types list|get|transfers|transfer-trigger` — Payroll integration
- `to config login|logout|show|set-url|completion` — Configuration
- `to status` — API health check
- `to raw <METHOD> <PATH>` — Escape hatch for any API endpoint

**Global options:** `--profile`, `--format table|json`, `--quiet`, `--yes`, `--verbose`, `--timeout`

[Full CLI Reference](https://travelotter.app/llms-full.txt#cli-reference)

## Full Reference

- [Complete API Documentation](https://travelotter.app/llms-full.txt): All endpoints with request/response schemas and examples