# Filter stops

Search for stops using filter criteria.

## Common Filters

- By location: { "filter": { "shipperLocationId": { "equalTo": "uuid" } } }
- By postal code: { "filter": { "postalCode": { "equalTo": "60601" } } }
- Recently updated: { "filter": { "updatedAt": { "greaterThan": "2025-01-01T00:00:00Z" } } }

To list the stops of one shipment, read the shipment instead: its orders
carry them in route order, which a filter cannot express.

Endpoint: POST /stops/filter
Version: 1.1.0
Security: BearerAuth

## Request fields (application/json):

  - `filter` (object)

  - `filter.id` (object)
    Filter options for UUID fields (all operations)

  - `filter.id.equalTo` (string)
    Exact match

  - `filter.id.notEqualTo` (string)
    Not equal to

  - `filter.id.in` (array)
    Matches any UUID in the array

  - `filter.id.notIn` (array)
    Does not match any UUID in the array

  - `filter.id.isNull` (boolean)
    Field is null (true) or not null (false)

  - `filter.sequence` (object)
    Filter options for integer fields

  - `filter.sequence.lessThan` (integer)
    Less than

  - `filter.sequence.lessThanOrEqualTo` (integer)
    Less than or equal to

  - `filter.sequence.greaterThan` (integer)
    Greater than

  - `filter.sequence.greaterThanOrEqualTo` (integer)
    Greater than or equal to

  - `filter.sequence.in` (array)
    Matches any value in the array

  - `filter.sequence.notIn` (array)
    Does not match any value in the array

  - `filter.postalCode` (object)
    Filter options for string fields

  - `filter.postalCode.includes` (string)
    Contains substring (case-insensitive)

  - `filter.postalCode.notIncludes` (string)
    Does not contain substring (case-insensitive)

  - `filter.postalCode.startsWith` (string)
    Starts with prefix (case-insensitive)

  - `filter.postalCode.notStartsWith` (string)
    Does not start with prefix (case-insensitive)

  - `filter.postalCode.endsWith` (string)
    Ends with suffix (case-insensitive)

  - `filter.postalCode.notEndsWith` (string)
    Does not end with suffix (case-insensitive)

  - `filter.airportCode` (object)
    Filter options for string fields

  - `filter.shipperLocationId` (object)
    Filter options for UUID fields (all operations)

  - `filter.createdAt` (object)
    Filter options for datetime fields

  - `filter.createdAt.lessThan` (string)
    Before this datetime

  - `filter.createdAt.lessThanOrEqualTo` (string)
    On or before this datetime

  - `filter.createdAt.greaterThan` (string)
    After this datetime

  - `filter.createdAt.greaterThanOrEqualTo` (string)
    On or after this datetime

  - `filter.updatedAt` (object)
    Filter options for datetime fields

  - `filter.and` (array)

  - `filter.or` (array)

  - `filter.not` (object)

  - `pageSize` (integer)

  - `cursor` (string)

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.id` (string, required)

  - `data.type` (string, required)
    Whether freight is collected (PICK) or delivered (DROP) at this stop.
    Enum: "PICK", "DROP"

  - `data.sequence` (integer, required)
    Position in the route, starting at 1.

  - `data.location` (object)
    Set when the stop was placed by location.

  - `data.location.id` (string, required)
    Resource UUID

  - `data.location.key` (string,null)
    Client-defined reference ID if set

  - `data.address` (object)
    Full address from the stop's linked location. Absent for a stop placed
by postal code, city or airport code, none of which carry a street
address.

  - `data.address.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `data.address.line2` (string,null)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `data.address.city` (string, required)
    City name
    Example: "Chicago"

  - `data.address.state` (string,null)
    State or province code
    Example: "IL"

  - `data.address.zipCode` (string,null)
    Postal / ZIP code
    Example: "60601"

  - `data.address.country` (string, required)
    Country name or code
    Example: "USA"

  - `data.address.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `data.address.latitude` (string,null)
    Latitude coordinate
    Example: "41.8781"

  - `data.address.longitude` (string,null)
    Longitude coordinate
    Example: "-87.6298"

  - `data.address.isAirportOrAirbase` (boolean, required)
    Whether this location is an airport or airbase

  - `data.address.isConstructionOrUtilitySite` (boolean, required)
    Whether this location is a construction or utility site

  - `data.address.isSmartyValidated` (boolean, required)
    Whether address has been validated by SmartyStreets
    Example: true

  - `data.address.obeysDst` (boolean, required)
    Whether this location observes daylight saving time
    Example: true

  - `data.address.cityId` (string,null)
    Reference to standardized city record (internal use)

  - `data.postalCode` (string,null)

  - `data.city` (object,null)

  - `data.city.name` (string)

  - `data.city.stateProvince` (string)

  - `data.airportCode` (string,null)

  - `data.requestedStartDate` (string,null)

  - `data.requestedEndDate` (string,null)

  - `data.requestedStartTime` (string,null)

  - `data.requestedEndTime` (string,null)

  - `data.actualArrival` (string,null)

  - `data.actualDeparture` (string,null)

  - `data.dropTrailer` (boolean)
    Whether the carrier drops the trailer rather than waiting.

  - `data.notes` (string,null)
    Instructions shown to the carrier.

  - `data.createdAt` (string, required)

  - `data.updatedAt` (string,null)

  - `pagination` (object, required)

  - `pagination.pageSize` (integer, required)
    Number of items per page
    Example: 50

  - `pagination.hasNextPage` (boolean, required)
    Whether there are more pages
    Example: true

  - `pagination.hasPreviousPage` (boolean)
    Whether there are previous pages

  - `pagination.endCursor` (string,null)
    Cursor for the next page (null if no next page)
    Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"

  - `errors` (array)
    Filter fields this endpoint did not apply. Present only when the
request used one; the request still succeeds and data is returned
without that clause, so treat the rows as unfiltered by these fields.

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array, required)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"