# Filter documents

Search for documents using filter criteria.

## Usage

Documents are typically associated with other entities (orders, loads, services).
Use filters to find documents by type, status, or date range.

## Example Filters

- Find all invoices: { "filter": { "type": { "equalTo": "INVOICE" } } }
- Find uploaded documents: { "filter": { "status": { "equalTo": "UPLOADED" } } }
- Find documents created today: { "filter": { "createdAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }

Endpoint: POST /documents/filter
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `filter` (object)
    Filter criteria for documents

  - `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.type` (object)
    Filter for document type field

  - `filter.type.equalTo` (string)
    Type of document.

Common types:
- INVOICE: Customer invoice
- BILL_OF_LADING: Bill of lading document
- RATE_CON: Rate confirmation
- PROOF_OF_DELIVERY: Proof of delivery (POD)
- CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
- W9: W-9 tax form
- CARRIER_INVOICE: Carrier invoice/bill
- LUMPER_RECEIPT: Lumper receipt
- DETENTION: Detention documentation
- DELIVERY_ORDER: Delivery order
- LOAD_TENDER: Load tender
- HOUSE_AIRWAY_BILL: House airway bill (HAWB)
- MASTER_AIRWAY_BILL: Master airway bill (MAWB)
- QUOTE: Quote document
- OTHER: Other document type
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `filter.type.notEqualTo` (string)
    Type of document.

Common types:
- INVOICE: Customer invoice
- BILL_OF_LADING: Bill of lading document
- RATE_CON: Rate confirmation
- PROOF_OF_DELIVERY: Proof of delivery (POD)
- CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
- W9: W-9 tax form
- CARRIER_INVOICE: Carrier invoice/bill
- LUMPER_RECEIPT: Lumper receipt
- DETENTION: Detention documentation
- DELIVERY_ORDER: Delivery order
- LOAD_TENDER: Load tender
- HOUSE_AIRWAY_BILL: House airway bill (HAWB)
- MASTER_AIRWAY_BILL: Master airway bill (MAWB)
- QUOTE: Quote document
- OTHER: Other document type
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `filter.type.in` (array)
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `filter.type.notIn` (array)
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `filter.status` (object)
    Filter for document status field

  - `filter.status.equalTo` (string)
    Upload status of the document.
- PENDING_UPLOAD: Document record created, file not yet uploaded
- UPLOADED: File has been uploaded to storage
    Enum: "PENDING_UPLOAD", "UPLOADED"

  - `filter.status.notEqualTo` (string)
    Upload status of the document.
- PENDING_UPLOAD: Document record created, file not yet uploaded
- UPLOADED: File has been uploaded to storage
    Enum: "PENDING_UPLOAD", "UPLOADED"

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

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

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

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

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

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

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

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

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

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

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

  - `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)
    Filter criteria for documents

  - `pageSize` (integer)
    Number of results per page

  - `cursor` (string)
    Pagination cursor from previous response

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.id` (string, required)
    Unique identifier for the document
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `data.key` (string,null)
    Client-defined key for external reference
    Example: "doc-inv-2025-001"

  - `data.type` (string, required)
    Type of document.

Common types:
- INVOICE: Customer invoice
- BILL_OF_LADING: Bill of lading document
- RATE_CON: Rate confirmation
- PROOF_OF_DELIVERY: Proof of delivery (POD)
- CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
- W9: W-9 tax form
- CARRIER_INVOICE: Carrier invoice/bill
- LUMPER_RECEIPT: Lumper receipt
- DETENTION: Detention documentation
- DELIVERY_ORDER: Delivery order
- LOAD_TENDER: Load tender
- HOUSE_AIRWAY_BILL: House airway bill (HAWB)
- MASTER_AIRWAY_BILL: Master airway bill (MAWB)
- QUOTE: Quote document
- OTHER: Other document type
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `data.fileName` (string, required)
    Original file name
    Example: "invoice-2025-001.pdf"

  - `data.extension` (string)
    File extension (without dot)
    Example: "pdf"

  - `data.contentType` (string, required)
    MIME content type
    Example: "application/pdf"

  - `data.fileSize` (integer,null)
    File size in bytes
    Example: 102400

  - `data.status` (string, required)
    Upload status of the document.
- PENDING_UPLOAD: Document record created, file not yet uploaded
- UPLOADED: File has been uploaded to storage
    Enum: "PENDING_UPLOAD", "UPLOADED"

  - `data.uploadUrl` (string,null)
    Pre-signed URL for uploading the file.
Only present immediately after document creation.
Expires after 15 minutes.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `data.downloadUrl` (string,null)
    Pre-signed URL for downloading the file.
Present when document status is UPLOADED.
Expires after 1 hour.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `data.tags` (object,null)
    Arbitrary key-value tags for the document
    Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}

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

  - `data.updatedAt` (string,null)
    When the document was last updated
    Example: "2025-01-15T10:35:00Z"

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