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

# 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

{
  "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:

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

# 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

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

Execute a TQL Query

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:

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

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

Reference Data

Currencies

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

Languages

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

Industries

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

Tax Rates

# 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

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:

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

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
Use date ranges with Fleet Tracking
See the full API Reference for all search endpoints