{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Search & Filtering","description":"The operational transportation management API. Full access to planning, tracking, invoicing, and integrations — built on the OTM5 open data standard.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"search--filtering","__idx":0},"children":["Search & Filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transportial provides powerful search capabilities across all entities. This guide covers pagination patterns, search endpoints, and TQL (Transportial Query Language) for advanced filtering."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":1},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All list endpoints follow the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{offset}/{amount}"]}," pattern:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/{entity}s/{offset}/{amount}\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["offset"]}," — Number of items to skip (0-based)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["amount"]}," — Number of items to return per page"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example","__idx":2},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# First page: items 0-19\ncurl -X GET \"https://api.otms.transportial.com/api/transportOrders/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Second page: items 20-39\ncurl -X GET \"https://api.otms.transportial.com/api/transportOrders/20/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paginated-response","__idx":3},"children":["Paginated Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"message\": \"OK\",\n  \"totalResults\": 142,\n  \"items\": [...]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalResults"]}," to calculate the total number of pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"search-endpoints","__idx":4},"children":["Search Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# GET — list all (paginated)\ncurl -X GET \"https://api.otms.transportial.com/api/transportOrders/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# POST — search with filters\ncurl -X POST \"https://api.otms.transportial.com/api/transportOrders/0/20\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"status\": \"requested\",\n    \"customer\": { \"id\": \"customer-uuid\" }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"common-filters","__idx":5},"children":["Common Filters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most search endpoints accept entity field names as filter keys:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Filter"},"children":["Filter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"requested\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by status"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Shipment\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partial name match"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"uuid\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by relation ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"2026-03-01\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by date"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tql--transportial-query-language","__idx":6},"children":["TQL — Transportial Query Language"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For advanced filtering, Transportial offers TQL — a query language that supports complex conditions across all entity types."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-available-fields","__idx":7},"children":["Get Available Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Discover which fields you can query for any entity type:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Get all fields for transport orders\ncurl -X GET \"https://api.otms.transportial.com/api/tql/fields/transportOrder\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"search-fields-by-keyword","__idx":8},"children":["Search Fields by Keyword"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/tql/fields/transportOrder/status/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"execute-a-tql-query","__idx":9},"children":["Execute a TQL Query"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/tql/query \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"entityType\": \"transportOrder\",\n    \"query\": \"status = requested AND customer.name LIKE Acme\",\n    \"offset\": 0,\n    \"amount\": 20\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"global-search","__idx":10},"children":["Global Search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search across all entity types at once:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/general/0/20\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"query\": \"Amsterdam\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"entity-structure","__idx":11},"children":["Entity Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get the empty structure of any entity type (useful for understanding available fields):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/entity/transportOrder\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reference-data","__idx":12},"children":["Reference Data"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"currencies","__idx":13},"children":["Currencies"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/currencies \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"languages","__idx":14},"children":["Languages"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/languages \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"industries","__idx":15},"children":["Industries"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/industries \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tax-rates","__idx":16},"children":["Tax Rates"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Get tax rates\ncurl -X GET https://api.otms.transportial.com/api/taxRates \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Update tax rates\ncurl -X PUT https://api.otms.transportial.com/api/taxRates \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '[\n    { \"name\": \"Standard\", \"rate\": 21 },\n    { \"name\": \"Reduced\", \"rate\": 9 },\n    { \"name\": \"Zero\", \"rate\": 0 }\n  ]'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pricing-categories","__idx":17},"children":["Pricing Categories"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/pricingCategories \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"date-based-queries","__idx":18},"children":["Date-Based Queries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many entities support date range filtering in the URL:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Trips by date\ncurl -X GET \"https://api.otms.transportial.com/api/vehicle/{id}/trips:byDate/2026-03-01/2026-03-31\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Activities by date\ncurl -X GET \"https://api.otms.transportial.com/api/chauffeur/{id}/activities:byDate/2026-03-01/2026-03-31\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Ledger entries by date\ncurl -X POST \"https://api.otms.transportial.com/api/ledgerEntriesByDateRange\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"startDate\": \"2026-03-01\",\n    \"endDate\": \"2026-03-31\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-mapping","__idx":19},"children":["Data Mapping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Convert key-value pairs to JSON structures:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT https://api.otms.transportial.com/api/mappingToJson \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"pairs\": [\n      { \"key\": \"name\", \"value\": \"Test Order\" },\n      { \"key\": \"status\", \"value\": \"requested\" }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":20},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply filters when ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/examples/managing-transport-orders"},"children":["Managing Transport Orders"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use date ranges with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/examples/fleet-tracking"},"children":["Fleet Tracking"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["See the full ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis"},"children":["API Reference"]}," for all search endpoints"]}]}]},"headings":[{"value":"Search & Filtering","id":"search--filtering","depth":1},{"value":"Pagination","id":"pagination","depth":2},{"value":"Example","id":"example","depth":3},{"value":"Paginated Response","id":"paginated-response","depth":3},{"value":"Search Endpoints","id":"search-endpoints","depth":2},{"value":"Common Filters","id":"common-filters","depth":3},{"value":"TQL — Transportial Query Language","id":"tql--transportial-query-language","depth":2},{"value":"Get Available Fields","id":"get-available-fields","depth":3},{"value":"Search Fields by Keyword","id":"search-fields-by-keyword","depth":3},{"value":"Execute a TQL Query","id":"execute-a-tql-query","depth":3},{"value":"Global Search","id":"global-search","depth":2},{"value":"Entity Structure","id":"entity-structure","depth":2},{"value":"Reference Data","id":"reference-data","depth":2},{"value":"Currencies","id":"currencies","depth":3},{"value":"Languages","id":"languages","depth":3},{"value":"Industries","id":"industries","depth":3},{"value":"Tax Rates","id":"tax-rates","depth":3},{"value":"Pricing Categories","id":"pricing-categories","depth":3},{"value":"Date-Based Queries","id":"date-based-queries","depth":2},{"value":"Data Mapping","id":"data-mapping","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Search & Filtering"}},"lastModified":"2026-03-22T21:04:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/search-and-filtering","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}