Skip to main content
GET
List Shipment Filter Values
← Logistics API Get the distinct values a field takes across your organization’s logistics requests (shipments), each with the number of shipments using it. Call it before rendering a filter so the dropdown offers only values that exist: the vehicle types your shipments actually use, the files they came from, the people who uploaded them.
field is free text, not a closed list — and an unsupported value does not return 422. It returns an empty array:
That makes “there are no shipments” and “I misspelled the field” look identical. The three accepted values are file_id, uploaded_by and vehicle_type; check your spelling against them before concluding the organization has no data.
Only active shipments are counted. Shipments in any other status (such as error) are excluded from these values. A filter built from this response therefore matches what List Logistics Requests returns by default (trip_status unset).

Request

Headers

string
required
UUID of the organization whose shipments you are filtering.Format: UUID
string
Your API key.

Query Parameters

string
required
The field to list values for. Three values are supported:
  • vehicle_type — value and label are both the TOC name, <vehicle>_<type> (e.g. van_3.5_t_diesel). It is the exact string the vehicle_type[] and filter_by=vehicle_type:in[...] filters of List Logistics Requests take. Shipments without a TOC are excluded. Sorted by name.
  • file_id — value is the id of the source file, label is the file name. Shipments created one by one or through the API have no file: they come back as one bucket whose value is the all-zero UUID 00000000-0000-0000-0000-000000000000.
  • uploaded_by — value is the id of the user who uploaded the shipments, label is that user’s first and last name. Shipments with no uploader are excluded.
Anything else returns an empty array rather than an error — see the warning above.
string
Only used with field=vehicle_type: narrows the list to the TOCs of the shipments linked to this project. Ignored for file_id and uploaded_by. A project with no shipments returns an empty list, not an error.Format: UUID

Response

string
The field that was queried, echoed back verbatim — including when it is not a supported one.
integer
How many distinct values were found.
array[object]
The distinct values, each with its shipment count.

Large organizations

When an organization has more than 250,000 active shipments, grouping every row would take minutes, so the values come from smaller sources and the counts become approximations:
  • count is a PostgreSQL planner estimate, not an exact count. Use it to rank options, not to report totals.
  • file_id lists the organization’s file uploads that were not deleted, newest first, and count is the number of rows the file had when it was uploaded: shipments deleted later are not subtracted. The no-file bucket is added at the end when the estimate finds any.
  • uploaded_by lists every member of the organization, sorted by name. Members who never uploaded a shipment can appear: filtering by them returns no rows.
  • vehicle_type lists the TOCs the organization’s active shipments use, with estimated counts. With project_id, the threshold applies to the shipments linked to the project: a project above 250,000 gets the organization’s TOCs, a superset of the project’s. It never offers a TOC the organization does not use.
Below the threshold every value and count is exact.

Example

Successful Response

Returns 200 OK.
A TOC name can cover several TOCs (one per region); their shipments are added into a single entry, because the filters take the name.

Common Errors

422 Unprocessable Entity

Cause: field is missing entirely, or project_id is not a valid UUID. A present but unsupported field does not fail: it succeeds with an empty array.

Use Cases

Offer only the vehicle types a list uses

The TOC catalogue has hundreds of entries, and an organization’s shipments use a handful. Populate the vehicle type dropdown from field=vehicle_type (with the project_id of the list you are showing, if any) so every option returns rows, then send the chosen names back to List Logistics Requests:

Find the shipments created without a file

The file_id bucket with the all-zero UUID counts the shipments created one by one or through the API. To list them, pass that value in a column filter, which reads it as “no file”: filter_by=file_id:in["00000000-0000-0000-0000-000000000000"]. The file_id[] parameter compares it literally and matches nothing.

List Logistics Requests

The shipments these values filter

Bulk Delete Requests by Filters

Apply the filter you just built to a bulk delete

List Available Vehicle Types

The full TOC catalogue, used or not

Logistics API

Everything the Logistics API covers