# Filter services

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" } } }

Endpoint: POST /services/filter
Version: 1.0.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.shipmentId` (object)
    Filter options for UUID fields (all operations)

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

  - `filter.serviceType` (object)

  - `filter.serviceType.equalTo` (string)
    Type of service.
- DRAYAGE: Port/rail drayage
- CUSTOMS_CLEARANCE: Customs brokerage
- WAREHOUSING: Warehouse storage
- CROSS_DOCK: Cross-dock handling
- TRANSLOAD: Transloading service
- FUMIGATION: Cargo fumigation
- INSPECTION: Cargo inspection
- DOCUMENTATION: Documentation handling
- INSURANCE: Cargo insurance
- CARGO_HANDLING: General cargo handling
- OTHER: Other service type
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `filter.serviceType.notEqualTo` (string)
    Type of service.
- DRAYAGE: Port/rail drayage
- CUSTOMS_CLEARANCE: Customs brokerage
- WAREHOUSING: Warehouse storage
- CROSS_DOCK: Cross-dock handling
- TRANSLOAD: Transloading service
- FUMIGATION: Cargo fumigation
- INSPECTION: Cargo inspection
- DOCUMENTATION: Documentation handling
- INSURANCE: Cargo insurance
- CARGO_HANDLING: General cargo handling
- OTHER: Other service type
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `filter.serviceType.in` (array)
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `filter.serviceType.notIn` (array)
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `filter.status` (object)

  - `filter.status.equalTo` (string)
    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
    Enum: "ACTIVE", "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID", "CANCELED"

  - `filter.status.notEqualTo` (string)
    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
    Enum: "ACTIVE", "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID", "CANCELED"

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

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

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

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

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

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

  - `filter.createdAt` (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)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.key` (string,null)
    Human-readable service ID
    Example: "SVC-12345"

  - `data.shipmentId` (string)
    Parent shipment

  - `data.shipmentKey` (string,null)
    Parent shipment friendly ID

  - `data.vendor` (object)
    Enhanced reference to a vendor profile.
Includes full vendor details in addition to id/key.

  - `data.vendor.id` (string, required)
    Vendor UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.vendor.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-VENDOR-ABC-001"

  - `data.vendor.friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

  - `data.vendor.name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `data.vendor.email` (string,null)
    Primary email address
    Example: "billing@abcwarehouse.com"

  - `data.vendor.phone` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `data.vendor.status` (string,null)
    Vendor status
    Example: "ACTIVE"

  - `data.vendor.currency` (string,null)
    Preferred currency code (ISO 4217)
    Example: "USD"

  - `data.vendor.createdAt` (string, required)
    When the vendor was created
    Example: "2025-01-15T10:00:00Z"

  - `data.vendor.updatedAt` (string, required)
    When the vendor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `data.vendorContact` (object)

  - `data.vendorContact.name` (string)

  - `data.vendorContact.phone` (string,null)

  - `data.vendorContact.email` (string,null)

  - `data.serviceType` (string)
    Type of service.
- DRAYAGE: Port/rail drayage
- CUSTOMS_CLEARANCE: Customs brokerage
- WAREHOUSING: Warehouse storage
- CROSS_DOCK: Cross-dock handling
- TRANSLOAD: Transloading service
- FUMIGATION: Cargo fumigation
- INSPECTION: Cargo inspection
- DOCUMENTATION: Documentation handling
- INSURANCE: Cargo insurance
- CARGO_HANDLING: General cargo handling
- OTHER: Other service type
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `data.status` (string, 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
    Enum: "ACTIVE", "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID", "CANCELED"

  - `data.description` (string,null)
    Service description

  - `data.charges` (array)
    Flattened charges array

  - `data.charges.chargeCode` (object)
    Reference to another resource (returned in responses)

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

  - `data.charges.description` (string,null)

  - `data.charges.amount` (number)

  - `data.charges.quantity` (number)

  - `data.totalCost` (number,null)
    Sum of all charges

  - `data.scheduledDate` (string,null)

  - `data.completedDate` (string,null)

  - `data.referenceNumber` (string,null)
    Vendor reference number

  - `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"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message