# Filter bill payments

Search for bill payments using filter criteria.

## Common Filters

- By carrier: { "filter": { "carrierId": { "equalTo": "uuid" } } }
- By vendor: { "filter": { "vendorId": { "equalTo": "uuid" } } }
- By factor: { "filter": { "carrierFactorId": { "equalTo": "uuid" } } }
- By date range: { "filter": { "paymentDate": { "gte": "2025-01-01", "lte": "2025-01-31" } } }
- By method: { "filter": { "paymentMethodType": { "equalTo": "check" } } }

Endpoint: POST /bill-payments/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.carrierId` (object)
    Filter options for UUID fields (all operations)

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

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

  - `filter.recipientType` (object)

  - `filter.recipientType.equalTo` (string)
    Type of recipient for the payment.
- CARRIER: Payment to a carrier
- VENDOR: Payment to a vendor
    Enum: "CARRIER", "VENDOR"

  - `filter.recipientType.in` (array)
    Enum: "CARRIER", "VENDOR"

  - `filter.paymentMethodType` (object)

  - `filter.paymentMethodType.equalTo` (string)
    Payment method used for the bill payment.
- ACH_WIRE: ACH wire transfer
- CHECK: Paper check
- CREDIT_CARD: Credit card payment
- EFT_DIRECT_DEPOSIT: EFT direct deposit
- E_TRANSFER: Electronic transfer
- VENMO: Venmo payment
    Enum: "ACH_WIRE", "CHECK", "CREDIT_CARD", "EFT_DIRECT_DEPOSIT", "E_TRANSFER", "VENMO"

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

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

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

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

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

  - `filter.totalAmount` (object)
    Filter options for float/number fields

  - `filter.totalAmount.lessThan` (number)
    Less than

  - `filter.totalAmount.lessThanOrEqualTo` (number)
    Less than or equal to

  - `filter.totalAmount.greaterThan` (number)
    Greater than

  - `filter.totalAmount.greaterThanOrEqualTo` (number)
    Greater than or equal to

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

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

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

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

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

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

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

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

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

  - `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)
    Client-defined key

  - `data.recipientType` (string, required)
    Type of recipient for the payment.
- CARRIER: Payment to a carrier
- VENDOR: Payment to a vendor
    Enum: "CARRIER", "VENDOR"

  - `data.carrier` (object)
    Enhanced reference to a carrier resource (returned in responses).
Includes full carrier details in addition to id/key.

Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

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

  - `data.carrier.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CARRIER-SWIFT"

  - `data.carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `data.carrier.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-987-6543"

  - `data.carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

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

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

  - `data.carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `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.friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

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

  - `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.carrierFactor` (object)

  - `data.carrierFactor.companyName` (string)

  - `data.carrierFactor.bankName` (string,null)

  - `data.paymentDate` (string, required)
    Date the payment was made

  - `data.paymentMethodType` (string)
    Payment method used for the bill payment.
- ACH_WIRE: ACH wire transfer
- CHECK: Paper check
- CREDIT_CARD: Credit card payment
- EFT_DIRECT_DEPOSIT: EFT direct deposit
- E_TRANSFER: Electronic transfer
- VENMO: Venmo payment
    Enum: "ACH_WIRE", "CHECK", "CREDIT_CARD", "EFT_DIRECT_DEPOSIT", "E_TRANSFER", "VENMO"

  - `data.reference` (string,null)
    Check number, transaction ID, etc.

  - `data.notes` (string,null)
    Additional notes

  - `data.totalAmount` (number, required)
    Total payment amount (sum of all applications)

  - `data.overpayment` (number,null)
    Amount paid in excess of invoice totals

  - `data.overpaymentCreditMemoId` (string,null)
    Credit memo created for overpayment

  - `data.applications` (array, required)
    Individual bill payments in this group

  - `data.applications.billId` (string, required)
    Bill (invoice) this payment applies to

  - `data.applications.billFriendlyId` (string,null)
    Human-readable bill ID

  - `data.applications.amount` (number, required)
    Amount applied to this bill

  - `data.applications.loadCarrierId` (string,null)
    Associated load carrier (for carrier bills)

  - `data.applications.vendedServiceId` (string,null)
    Associated vended service (for vendor bills)

  - `data.applications.shipmentId` (string,null)

  - `data.applications.shipmentFriendlyId` (string,null)

  - `data.qboId` (string,null)
    QuickBooks Online bill payment ID

  - `data.syncStatus` (string,null)
    QuickBooks sync status
    Enum: "pending", "synced", "error"

  - `data.syncError` (string,null)
    QuickBooks sync error message

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