---
title: "Filter services"
method: POST
path: "/services/filter"
tags: ["Services"]
---

# Filter services

`POST /services/filter`

Search for services using filter criteria.

## Common Filters

- By shipment: `{ "filter": { "shipmentId": { "equalTo": "uuid" } } }`
- By vendor: `{ "filter": { "vendorId": { "equalTo": "uuid" } } }`
- Awaiting invoice: `{ "filter": { "status": { "equalTo": "AWAITING_INVOICE" } } }`

## Request body

- ServiceFilterRequest
  - `filter` ServiceFilter
    - `id` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `shipmentId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `vendorId` UUIDFilter — Filter options for UUID fields (all operations)
      - `equalTo` string, uuid — Exact match
      - `notEqualTo` string, uuid — Not equal to
      - `in` string[] — Matches any UUID in the array
      - `notIn` string[] — Does not match any UUID in the array
      - `isNull` boolean — Field is null (true) or not null (false)
    - `status` ServiceStatusFilter
      - `equalTo` 'ACTIVE' | 'AWAITING_INVOICE' | 'INVOICE_IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' | 'CANCELED' — Current status of the service. **Active states:** - `ACTIVE`: Service is active/in progress **Billing states (AP):** - `AWAITING_INVOICE`: Waiting for vendor invoice - `INVOICE_IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved for payment - `PAID`: Paid to vendor **Final states:** - `CANCELED`: Service canceled
      - `notEqualTo` 'ACTIVE' | 'AWAITING_INVOICE' | 'INVOICE_IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' | 'CANCELED' — Current status of the service. **Active states:** - `ACTIVE`: Service is active/in progress **Billing states (AP):** - `AWAITING_INVOICE`: Waiting for vendor invoice - `INVOICE_IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved for payment - `PAID`: Paid to vendor **Final states:** - `CANCELED`: Service canceled
      - `in` ServiceStatus[]
      - `notIn` ServiceStatus[]
    - `scheduledDate` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `completedDate` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `createdAt` DatetimeFilter — Filter options for datetime fields
      - `equalTo` string, date-time — Exact match
      - `notEqualTo` string, date-time — Not equal to
      - `lessThan` string, date-time — Before this datetime
      - `lessThanOrEqualTo` string, date-time — On or before this datetime
      - `greaterThan` string, date-time — After this datetime
      - `greaterThanOrEqualTo` string, date-time — On or after this datetime
      - `isNull` boolean — Field is null (true) or not null (false)
    - `and` ServiceFilter[]
    - `or` ServiceFilter[]
    - `not` ServiceFilter — recursive
  - `pageSize` integer
  - `cursor` string

## Response `200`

Services matching filter criteria

- object
  - `data` Service[], required
    - `id` string, uuid, required
    - `key` string, nullable — Human-readable service ID
    - `shipmentId` string, uuid — Parent shipment
    - `shipmentKey` string, nullable — Parent shipment friendly ID
    - `vendor` VendorReference — Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.
      - `id` string, uuid, required — Vendor UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `friendlyId` string, required — Human-readable vendor identifier
      - `name` string, required — Vendor legal name
      - `email` string, email, nullable — Primary email address
      - `phone` string, nullable — Primary phone number
      - `status` string, nullable — Vendor status
      - `currency` string, nullable — Preferred currency code (ISO 4217)
      - `createdAt` string, date-time, required — When the vendor was created
      - `updatedAt` string, date-time, required — When the vendor was last updated
    - `vendorContact` object
      - `id` string, uuid
      - `name` string
      - `phone` string, nullable
      - `email` string, nullable
    - `status` 'ACTIVE' | 'AWAITING_INVOICE' | 'INVOICE_IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' | 'CANCELED', required — Current status of the service. **Active states:** - `ACTIVE`: Service is active/in progress **Billing states (AP):** - `AWAITING_INVOICE`: Waiting for vendor invoice - `INVOICE_IN_REVIEW`: Invoice received, under review - `APPROVED_TO_PAY`: Approved for payment - `PAID`: Paid to vendor **Final states:** - `CANCELED`: Service canceled
    - `description` string, nullable — Service description
    - `charges` ServiceCharge[] — Flattened charges array
      - `id` string, uuid
      - `chargeCode` ResourceReference — Reference to another resource (returned in responses)
        - `id` string, uuid, required — Resource UUID
        - `key` string, nullable — Client-defined reference ID if set
      - `description` string, nullable
      - `amount` number
      - `quantity` number
    - `totalCost` number, nullable — Sum of all charges
    - `scheduledDate` string, date, nullable
    - `completedDate` string, date, nullable
    - `referenceNumber` string, nullable — Vendor reference number
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, nullable
  - `pagination` PaginationInfo, required
    - `pageSize` integer, required — Number of items per page
    - `hasNextPage` boolean, required — Whether there are more pages
    - `hasPreviousPage` boolean — Whether there are previous pages
    - `endCursor` string, nullable — Cursor for the next page (null if no next page)

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values

---

[API](https://skmtc.dev/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.dev/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/7af4e91459ca/schema)