# Search & Filtering

Transportial provides powerful search capabilities across all entities. This guide covers pagination patterns, search endpoints, and TQL (Transportial Query Language) for advanced filtering.

## Pagination

All list endpoints follow the `{offset}/{amount}` pattern:


```
GET /api/{entity}s/{offset}/{amount}
```

- **offset** — Number of items to skip (0-based)
- **amount** — Number of items to return per page


### Example


```bash
# First page: items 0-19
curl -X GET "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Second page: items 20-39
curl -X GET "https://api.otms.transportial.com/api/transportOrders/20/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Paginated Response


```json
{
  "success": true,
  "message": "OK",
  "totalResults": 142,
  "items": [...]
}
```

Use `totalResults` to calculate the total number of pages.

## Search Endpoints

Most entities support a POST search endpoint on the same path as the GET list endpoint. POST allows you to send filter criteria in the request body:


```bash
# GET — list all (paginated)
curl -X GET "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# POST — search with filters
curl -X POST "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested",
    "customer": { "id": "customer-uuid" }
  }'
```

### Common Filters

Most search endpoints accept entity field names as filter keys:

| Filter | Example | Description |
|  --- | --- | --- |
| `status` | `"requested"` | Filter by status |
| `name` | `"Shipment"` | Partial name match |
| `customer.id` | `"uuid"` | Filter by relation ID |
| `createdAt` | `"2026-03-01"` | Filter by date |


## TQL — Transportial Query Language

For advanced filtering, Transportial offers TQL — a query language that supports complex conditions across all entity types.

### Get Available Fields

Discover which fields you can query for any entity type:


```bash
# Get all fields for transport orders
curl -X GET "https://api.otms.transportial.com/api/tql/fields/transportOrder" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Search Fields by Keyword


```bash
curl -X GET "https://api.otms.transportial.com/api/tql/fields/transportOrder/status/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Execute a TQL Query


```bash
curl -X POST https://api.otms.transportial.com/api/tql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "entityType": "transportOrder",
    "query": "status = requested AND customer.name LIKE Acme",
    "offset": 0,
    "amount": 20
  }'
```

## Global Search

Search across all entity types at once:


```bash
curl -X POST "https://api.otms.transportial.com/api/general/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "query": "Amsterdam"
  }'
```

## Entity Structure

Get the empty structure of any entity type (useful for understanding available fields):


```bash
curl -X GET "https://api.otms.transportial.com/api/entity/transportOrder" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Reference Data

### Currencies


```bash
curl -X GET https://api.otms.transportial.com/api/currencies \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Languages


```bash
curl -X GET https://api.otms.transportial.com/api/languages \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Industries


```bash
curl -X GET https://api.otms.transportial.com/api/industries \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Tax Rates


```bash
# Get tax rates
curl -X GET https://api.otms.transportial.com/api/taxRates \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update tax rates
curl -X PUT https://api.otms.transportial.com/api/taxRates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '[
    { "name": "Standard", "rate": 21 },
    { "name": "Reduced", "rate": 9 },
    { "name": "Zero", "rate": 0 }
  ]'
```

### Pricing Categories


```bash
curl -X GET https://api.otms.transportial.com/api/pricingCategories \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Date-Based Queries

Many entities support date range filtering in the URL:


```bash
# Trips by date
curl -X GET "https://api.otms.transportial.com/api/vehicle/{id}/trips:byDate/2026-03-01/2026-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Activities by date
curl -X GET "https://api.otms.transportial.com/api/chauffeur/{id}/activities:byDate/2026-03-01/2026-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Ledger entries by date
curl -X POST "https://api.otms.transportial.com/api/ledgerEntriesByDateRange" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'
```

## Data Mapping

Convert key-value pairs to JSON structures:


```bash
curl -X PUT https://api.otms.transportial.com/api/mappingToJson \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "pairs": [
      { "key": "name", "value": "Test Order" },
      { "key": "status", "value": "requested" }
    ]
  }'
```

## Next Steps

- Apply filters when [Managing Transport Orders](/examples/managing-transport-orders)
- Use date ranges with [Fleet Tracking](/examples/fleet-tracking)
- See the full [API Reference](/apis) for all search endpoints