---
title: "Create saved search"
method: POST
path: "/saved-searches"
tags: ["Saved Searches"]
---

# Create saved search

`POST /saved-searches`

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.

## Request body

- SavedSearchInput — Input for creating a new saved search
  - `name` string, required — Display name for the saved search (required)
  - `preferenceType` 'SHIPMENT' | 'INVOICE' | 'BILL' | 'USER' | 'CUSTOMER' | 'VENDOR' | 'QUOTE' | 'COMMISSION' | 'CARRIER' | 'INVOICE_PAYMENT' | 'BILL_PAYMENT' | 'LOAD' | 'TRUCK_POSTING' | 'LOCATION', required — Type of entity this saved search applies to. Each type corresponds to a specific entity's search view. **Entity Mapping:** - `INVOICE`: Customer invoices (AR Invoices) - money owed to you - `BILL`: Vendor/Carrier bills (AP Invoices) - money you owe - `INVOICE_PAYMENT`: Customer payment groups (AR Payment Groups) - `BILL_PAYMENT`: Vendor/Carrier payment groups (AP Payment Groups)
  - `jsonValue` SearchConfigurationState, required — The saved search configuration state containing criteria, sorting, and display preferences. This is stored in the jsonValue field.
    - `searchCriteria` object — Search criteria configuration
      - `filters` object[] — Array of field-level search filters
        - `field` string, required — The field name to filter on
        - `searchCriteria` object, required — The search criteria for this field
          - `operator` string, required — Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
          - `values` union[] — Array of values for multi-value operators
            - union
              - …
          - `value` union — Single value for single-value operators
            - string
            - number
            - boolean
          - `min` union — Minimum value for range operators
            - string
            - number
          - `max` union — Maximum value for range operators
            - string
            - number
          - `minRelative` integer — Relative minimum (e.g., -7 for 7 units ago)
          - `minRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for minRelative
          - `maxRelative` integer — Relative maximum
          - `maxRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for maxRelative
          - `valueRelative` integer — Relative value
          - `valueRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for valueRelative
    - `sorting` object[] — Sort configuration
      - `id` string, required — Field name to sort by
      - `desc` boolean, required — Sort in descending order if true
    - `columnVisibility` object — Column visibility settings (key is column name, value is visibility)
    - `columnOrder` string[] — Order of columns for display
  - `isPublic` boolean — Whether this saved search is visible to all users in the organization
  - `groupId` string, uuid — Optional group this saved search belongs to

## Response `201`

Saved search created successfully

- SavedSearch — A saved search configuration that can be used to quickly apply predefined search criteria, sorting, and display preferences. Saved searches are stored per organization and can be shared publicly or kept private to a specific user.
  - `object` 'SAVED_SEARCH' — Object type identifier
  - `id` string, uuid, required — Unique saved search identifier
  - `name` string, required — Display name for the saved search
  - `preferenceType` 'SHIPMENT' | 'INVOICE' | 'BILL' | 'USER' | 'CUSTOMER' | 'VENDOR' | 'QUOTE' | 'COMMISSION' | 'CARRIER' | 'INVOICE_PAYMENT' | 'BILL_PAYMENT' | 'LOAD' | 'TRUCK_POSTING' | 'LOCATION', required — Type of entity this saved search applies to. Each type corresponds to a specific entity's search view. **Entity Mapping:** - `INVOICE`: Customer invoices (AR Invoices) - money owed to you - `BILL`: Vendor/Carrier bills (AP Invoices) - money you owe - `INVOICE_PAYMENT`: Customer payment groups (AR Payment Groups) - `BILL_PAYMENT`: Vendor/Carrier payment groups (AP Payment Groups)
  - `jsonValue` SearchConfigurationState — The saved search configuration state containing criteria, sorting, and display preferences. This is stored in the jsonValue field.
    - `searchCriteria` object — Search criteria configuration
      - `filters` object[] — Array of field-level search filters
        - `field` string, required — The field name to filter on
        - `searchCriteria` object, required — The search criteria for this field
          - `operator` string, required — Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
          - `values` union[] — Array of values for multi-value operators
            - union
              - …
          - `value` union — Single value for single-value operators
            - string
            - number
            - boolean
          - `min` union — Minimum value for range operators
            - string
            - number
          - `max` union — Maximum value for range operators
            - string
            - number
          - `minRelative` integer — Relative minimum (e.g., -7 for 7 units ago)
          - `minRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for minRelative
          - `maxRelative` integer — Relative maximum
          - `maxRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for maxRelative
          - `valueRelative` integer — Relative value
          - `valueRelativeUnit` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' — Time unit for valueRelative
    - `sorting` object[] — Sort configuration
      - `id` string, required — Field name to sort by
      - `desc` boolean, required — Sort in descending order if true
    - `columnVisibility` object — Column visibility settings (key is column name, value is visibility)
    - `columnOrder` string[] — Order of columns for display
  - `isPublic` boolean, nullable — Whether this saved search is visible to all users in the organization. If false or null, only the owner can see it.
  - `ownedByUser` string, uuid, nullable — User ID who owns this saved search. Null means it's an organization-level saved search.
  - `groupId` string, uuid, nullable — Optional group this saved search belongs to
  - `createdAt` string, date-time, required — Timestamp when saved search was created
  - `updatedAt` string, date-time, required — Timestamp when saved search was last updated

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/53b310bb74a0/schema)