--- title: "Filter bill payments" method: POST path: "/bill-payments/filter" tags: ["Bill Payments"] --- # Filter bill payments `POST /bill-payments/filter` 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" } } }` ## Request body - BillPaymentFilterRequest - `filter` BillPaymentFilter - `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) - `carrierId` 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) - `carrierFactorId` 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) - `recipientType` object - `equalTo` 'CARRIER' | 'VENDOR' — Type of recipient for the payment. - `CARRIER`: Payment to a carrier - `VENDOR`: Payment to a vendor - `in` BillPaymentRecipientType[] - `paymentMethodType` BillPaymentMethodTypeFilter - `equalTo` 'ACH_WIRE' | 'CHECK' | 'CREDIT_CARD' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'VENMO' | 'ZELLE' — 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 - `ZELLE`: Zelle payment - `in` BillPaymentMethodType[] - `paymentDate` 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) - `totalAmount` FloatFilter — Filter options for float/number fields - `equalTo` number, float — Exact match - `notEqualTo` number, float — Not equal to - `lessThan` number, float — Less than - `lessThanOrEqualTo` number, float — Less than or equal to - `greaterThan` number, float — Greater than - `greaterThanOrEqualTo` number, float — Greater than or equal to - `isNull` boolean — Field is null (true) or not null (false) - `reference` StringFilter — Filter options for string fields - `equalTo` string — Exact match - `notEqualTo` string — Not equal to - `in` string[] — Matches any value in the array - `notIn` string[] — Does not match any value in the array - `includes` string — Contains substring (case-insensitive) - `notIncludes` string — Does not contain substring (case-insensitive) - `startsWith` string — Starts with prefix (case-insensitive) - `notStartsWith` string — Does not start with prefix (case-insensitive) - `endsWith` string — Ends with suffix (case-insensitive) - `notEndsWith` string — Does not end with suffix (case-insensitive) - `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` BillPaymentFilter[] - `or` BillPaymentFilter[] - `not` BillPaymentFilter — recursive - `pageSize` integer - `cursor` string ## Response `200` Bill payments matching filter criteria - object - `data` BillPayment[], required - `id` string, uuid, required - `key` string, nullable — Client-defined key - `recipientType` 'CARRIER' | 'VENDOR', required — Type of recipient for the payment. - `CARRIER`: Payment to a carrier - `VENDOR`: Payment to a vendor - `carrier` CarrierReference — 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. - `id` string, uuid, required — Carrier UUID - `key` string, nullable — Client-defined reference ID if set - `name` string, required — Carrier company name - `phoneNumber` string, nullable — Primary phone number - `email` string, email, nullable — Primary email address - `createdAt` string, date-time, required — When the carrier was created - `updatedAt` string, date-time, required — When the carrier was last updated - `deletedAt` string, date-time, nullable — When the carrier was soft deleted (null if active) - `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 - `carrierFactor` BillPaymentsCarrierFactorReference - `id` string, uuid - `companyName` string - `bankName` string, nullable - `paymentDate` string, date, required — Date the payment was made - `paymentMethodType` 'ACH_WIRE' | 'CHECK' | 'CREDIT_CARD' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'VENMO' | 'ZELLE' — 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 - `ZELLE`: Zelle payment - `reference` string, nullable — Check number, transaction ID, etc. - `notes` string, nullable — Additional notes - `totalAmount` number, required — Total payment amount (sum of all applications) - `overpayment` number, nullable — Amount paid in excess of invoice totals - `overpaymentCreditMemoId` string, uuid, nullable — Credit memo created for overpayment - `applications` BillPaymentApplication[], required — Individual bill payments in this group - `id` string, uuid, required - `billId` string, uuid, required — Bill (invoice) this payment applies to - `billFriendlyId` string, nullable — Human-readable bill ID - `amount` number, required — Amount applied to this bill - `loadCarrierId` string, uuid, nullable — Associated load carrier (for carrier bills) - `vendedServiceId` string, uuid, nullable — Associated vended service (for vendor bills) - `shipmentId` string, uuid, nullable - `shipmentFriendlyId` string, nullable - `qboId` string, nullable — QuickBooks Online bill payment ID - `syncStatus` 'pending' | 'synced' | 'error', nullable — QuickBooks sync status - `syncError` string, nullable — QuickBooks sync error message - `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)