# Filter customer contacts

Query customer contacts using flexible filter criteria with AND/OR logic.

By default, only non-deleted customer contacts are returned (deletedAt: { isNull: true }).
Override this by explicitly setting deletedAt filter criteria.

Endpoint: POST /customer-contacts/filter
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `filter` (object)
    Filter criteria (optional - omit to return all contacts).

Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
    Example: {"and":[{"isPrimary":{"equalTo":true}},{"contactTypes":{"includes":"BILLING"}}]}

  - `filter.and` (array)
    All conditions must match (recursive)
    Example: [{"isPrimary":{"equalTo":true}},{"contactTypes":{"includes":"BILLING"}}]

  - `filter.or` (array)
    At least one condition must match (recursive)

  - `filter.not` (object)
    Negates the filter

  - `filter.id` (object)
    Filter options for ID fields (limited operations - exact match only)

  - `filter.id.equalTo` (string)
    Exact match

  - `filter.id.in` (array)
    Matches any UUID in the array

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

  - `filter.customerId.notEqualTo` (string)
    Not equal to

  - `filter.customerId.notIn` (array)
    Does not match any UUID in the array

  - `filter.customerId.isNull` (boolean)
    Field is null (true) or not null (false)

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

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

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

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

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

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

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

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

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

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

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

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

  - `filter.isPrimary` (object)
    Filter options for boolean fields

  - `filter.contactTypes` (object)
    Filter for contact type enum array field

  - `filter.contactTypes.includes` (string)
    Array contains this contact type
    Enum: "ACCOUNT_MANAGER", "BILLING", "DOCK_SHIPPING", "EMERGENCY", "LOCATION_MANAGER", "OWNER", "PROCUREMENT", "PURCHASING", "RATES_PRICING", "RECEIVING", "SHIPPING"

  - `filter.contactTypes.notIncludes` (string)
    Array does not contain this contact type
    Enum: "ACCOUNT_MANAGER", "BILLING", "DOCK_SHIPPING", "EMERGENCY", "LOCATION_MANAGER", "OWNER", "PROCUREMENT", "PURCHASING", "RATES_PRICING", "RECEIVING", "SHIPPING"

  - `filter.notifications` (object)
    Filter for notification type enum array field

  - `filter.notifications.includes` (string)
    Array contains this notification type
    Enum: "SHIPMENT_DELIVERED", "SHIPMENT_IN_TRANSIT", "SHIPMENT_LOADING", "SHIPMENT_OUT_FOR_DELIVERY", "SHIPMENT_PICKED_UP", "SHIPMENT_TENDER_REJECTED", "SHIPMENT_UNLOADING"

  - `filter.notifications.notIncludes` (string)
    Array does not contain this notification type
    Enum: "SHIPMENT_DELIVERED", "SHIPMENT_IN_TRANSIT", "SHIPMENT_LOADING", "SHIPMENT_OUT_FOR_DELIVERY", "SHIPMENT_PICKED_UP", "SHIPMENT_TENDER_REJECTED", "SHIPMENT_UNLOADING"

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

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

  - `filter.key` (object)
    Filter options for client key fields (limited operations - exact match only)

  - `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.deletedAt` (object)
    Filter options for datetime fields

  - `pageSize` (integer)
    Number of results per page
    Example: 50

  - `cursor` (string)
    Pagination cursor for next page

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.object` (string)
    Object type identifier
    Enum: "CUSTOMER_CONTACT"

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

  - `data.customer` (object, required)
    Customer this contact belongs to (full customer details)

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

  - `data.customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `data.customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

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

  - `data.customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

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

  - `data.customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

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

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

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

  - `data.name` (string, required)
    Contact person's name (denormalized from ContactInfo for convenience)
    Example: "John Smith"

  - `data.contactInfo` (object, required)
    Contact information details (email, phone, title) - nested from parent Contact record

  - `data.contactInfo.name` (string, required)
    Contact person's full name
    Example: "John Smith"

  - `data.contactInfo.email` (string,null)
    Email address
    Example: "john.smith@example.com"

  - `data.contactInfo.phoneNumber` (string,null)
    Phone number
    Example: "+1-555-0100"

  - `data.contactInfo.title` (string,null)
    Job title or position
    Example: "Operations Manager"

  - `data.phoneExtension` (string,null)
    Phone extension specific to this contact role
    Example: "1234"

  - `data.isPrimary` (boolean, required)
    Whether this is the primary contact for the customer
    Example: true

  - `data.contactTypes` (array,null)
    Types/roles this contact serves
    Enum: "ACCOUNT_MANAGER", "BILLING", "DOCK_SHIPPING", "EMERGENCY", "LOCATION_MANAGER", "OWNER", "PROCUREMENT", "PURCHASING", "RATES_PRICING", "RECEIVING", "SHIPPING"

  - `data.notifications` (array,null)
    Shipment notification types to send to this contact
    Enum: "SHIPMENT_DELIVERED", "SHIPMENT_IN_TRANSIT", "SHIPMENT_LOADING", "SHIPMENT_OUT_FOR_DELIVERY", "SHIPMENT_PICKED_UP", "SHIPMENT_TENDER_REJECTED", "SHIPMENT_UNLOADING"

  - `data.invitedUser` (any)
    User account invited/created for this contact (full user details)

  - `data.deletedBy` (any)
    User who deleted this contact (full user details)

  - `data.key` (string,null)
    Client-defined reference identifier
    Example: "ERP-CONTACT-JOHN-001"

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

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

  - `pageInfo` (object, required)

  - `pageInfo.pageSize` (integer, required)
    Number of items per page
    Example: 50

  - `pageInfo.hasNextPage` (boolean, required)
    Whether there are more pages
    Example: true

  - `pageInfo.hasPreviousPage` (boolean)
    Whether there are previous pages

  - `pageInfo.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 500 fields (application/json):

  - `error` (string, required)
    Error code

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