# Create saved search

Create a new saved search configuration in your organization.
The saved search can be used to quickly apply predefined search criteria, sorting, and display preferences.

The saved search will be owned by the authenticated user unless otherwise specified.

Endpoint: POST /saved-searches
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `name` (string, required)
    Display name for the saved search (required)
    Example: "Active Shipments - West Coast"

  - `preferenceType` (string, required)
    The entity type this saved search applies to (required).
Determines which search endpoint can use this saved search.
    Enum: "SHIPMENT", "INVOICE", "BILL", "USER", "CUSTOMER", "VENDOR", "QUOTE", "COMMISSION", "CARRIER", "INVOICE_PAYMENT", "BILL_PAYMENT", "LOAD", "TRUCK_POSTING", "LOCATION"

  - `jsonValue` (object, required)
    The saved search configuration (required)
    Example: {"searchCriteria":{"filters":[{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]},"sorting":[{"id":"createdAt","desc":true}],"columnVisibility":{"status":true,"createdAt":true},"columnOrder":["id","status","createdAt"]}

  - `jsonValue.searchCriteria` (object)
    Search criteria configuration
    Example: {"filters":[{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]}

  - `jsonValue.searchCriteria.filters` (array)
    Array of field-level search filters
    Example: [{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]

  - `jsonValue.searchCriteria.filters.field` (string, required)
    The field name to filter on
    Example: "status"

  - `jsonValue.searchCriteria.filters.searchCriteria` (object, required)
    The search criteria for this field

  - `jsonValue.searchCriteria.filters.searchCriteria.operator` (string, required)
    Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
    Example: "ONE_OF"

  - `jsonValue.searchCriteria.filters.searchCriteria.values` (array)
    Array of values for multi-value operators
    Example: ["ACTIVE","PENDING"]

  - `jsonValue.searchCriteria.filters.searchCriteria.value` (any)
    Single value for single-value operators

  - `jsonValue.searchCriteria.filters.searchCriteria.min` (any)
    Minimum value for range operators

  - `jsonValue.searchCriteria.filters.searchCriteria.max` (any)
    Maximum value for range operators

  - `jsonValue.searchCriteria.filters.searchCriteria.minRelative` (integer)
    Relative minimum (e.g., -7 for 7 units ago)

  - `jsonValue.searchCriteria.filters.searchCriteria.minRelativeUnit` (string)
    Time unit for minRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.searchCriteria.filters.searchCriteria.maxRelative` (integer)
    Relative maximum

  - `jsonValue.searchCriteria.filters.searchCriteria.maxRelativeUnit` (string)
    Time unit for maxRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.searchCriteria.filters.searchCriteria.valueRelative` (integer)
    Relative value

  - `jsonValue.searchCriteria.filters.searchCriteria.valueRelativeUnit` (string)
    Time unit for valueRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.sorting` (array)
    Sort configuration
    Example: [{"id":"createdAt","desc":true}]

  - `jsonValue.sorting.id` (string, required)
    Field name to sort by
    Example: "createdAt"

  - `jsonValue.sorting.desc` (boolean, required)
    Sort in descending order if true
    Example: true

  - `jsonValue.columnVisibility` (object)
    Column visibility settings (key is column name, value is visibility)
    Example: {"status":true,"createdAt":true}

  - `jsonValue.columnOrder` (array)
    Order of columns for display
    Example: ["id","status","createdAt"]

  - `isPublic` (boolean)
    Whether this saved search is visible to all users in the organization
    Example: true

  - `pinned` (boolean)
    Whether this saved search is pinned for quick access
    Example: true

  - `groupId` (string)
    Optional group this saved search belongs to

## Response 201 fields (application/json):

  - `object` (string)
    Object type identifier
    Enum: "SAVED_SEARCH"

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

  - `name` (string, required)
    Display name for the saved search
    Example: "Active Shipments - West Coast"

  - `preferenceType` (string, required)
    The entity type this saved search applies to.
Must match the search endpoint where this saved search will be used.
    Enum: "SHIPMENT", "INVOICE", "BILL", "USER", "CUSTOMER", "VENDOR", "QUOTE", "COMMISSION", "CARRIER", "INVOICE_PAYMENT", "BILL_PAYMENT", "LOAD", "TRUCK_POSTING", "LOCATION"

  - `jsonValue` (object)
    The saved search configuration (criteria, sorting, display preferences)
    Example: {"searchCriteria":{"filters":[{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]},"sorting":[{"id":"createdAt","desc":true}],"columnVisibility":{"status":true,"createdAt":true},"columnOrder":["id","status","createdAt"]}

  - `jsonValue.searchCriteria` (object)
    Search criteria configuration
    Example: {"filters":[{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]}

  - `jsonValue.searchCriteria.filters` (array)
    Array of field-level search filters
    Example: [{"field":"status","searchCriteria":{"operator":"ONE_OF","values":["ACTIVE","PENDING"]}}]

  - `jsonValue.searchCriteria.filters.field` (string, required)
    The field name to filter on
    Example: "status"

  - `jsonValue.searchCriteria.filters.searchCriteria` (object, required)
    The search criteria for this field

  - `jsonValue.searchCriteria.filters.searchCriteria.operator` (string, required)
    Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
    Example: "ONE_OF"

  - `jsonValue.searchCriteria.filters.searchCriteria.values` (array)
    Array of values for multi-value operators
    Example: ["ACTIVE","PENDING"]

  - `jsonValue.searchCriteria.filters.searchCriteria.value` (any)
    Single value for single-value operators

  - `jsonValue.searchCriteria.filters.searchCriteria.min` (any)
    Minimum value for range operators

  - `jsonValue.searchCriteria.filters.searchCriteria.max` (any)
    Maximum value for range operators

  - `jsonValue.searchCriteria.filters.searchCriteria.minRelative` (integer)
    Relative minimum (e.g., -7 for 7 units ago)

  - `jsonValue.searchCriteria.filters.searchCriteria.minRelativeUnit` (string)
    Time unit for minRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.searchCriteria.filters.searchCriteria.maxRelative` (integer)
    Relative maximum

  - `jsonValue.searchCriteria.filters.searchCriteria.maxRelativeUnit` (string)
    Time unit for maxRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.searchCriteria.filters.searchCriteria.valueRelative` (integer)
    Relative value

  - `jsonValue.searchCriteria.filters.searchCriteria.valueRelativeUnit` (string)
    Time unit for valueRelative
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `jsonValue.sorting` (array)
    Sort configuration
    Example: [{"id":"createdAt","desc":true}]

  - `jsonValue.sorting.id` (string, required)
    Field name to sort by
    Example: "createdAt"

  - `jsonValue.sorting.desc` (boolean, required)
    Sort in descending order if true
    Example: true

  - `jsonValue.columnVisibility` (object)
    Column visibility settings (key is column name, value is visibility)
    Example: {"status":true,"createdAt":true}

  - `jsonValue.columnOrder` (array)
    Order of columns for display
    Example: ["id","status","createdAt"]

  - `isPublic` (boolean,null)
    Whether this saved search is visible to all users in the organization.
If false or null, only the owner can see it.
    Example: true

  - `pinned` (boolean,null)
    Whether this saved search is pinned for quick access
    Example: true

  - `ownedByUser` (string,null)
    User ID who owns this saved search.
Null means it's an organization-level saved search.
    Example: "550e8400-e29b-41d4-a716-446655440001"

  - `groupId` (string,null)
    Optional group this saved search belongs to

  - `createdAt` (string, required)
    Timestamp when saved search was created
    Example: "2025-01-15T10:00:00Z"

  - `updatedAt` (string, required)
    Timestamp when saved search was last updated
    Example: "2025-01-15T14:30:00Z"

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

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

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